Google Researcher MCP Server

Professional research tools for AI assistants - Google Search, web scraping, academic papers, patents, and more

Features

Use Cases

• Research Assistants: Enable Claude to search the web and synthesize information
• Content Creation: Gather sources, citations, and supporting evidence
• Academic Research: Find papers, extract citations, track research progress
• Competitive Intelligence: Patent searches, company research, market analysis
• News Monitoring: Track breaking news, industry updates, specific sources
• Technical Documentation: Extract content from docs, tutorials, and references

Comparison with Alternatives

---

This is a Model Context Protocol (MCP) server that enables AI assistants like Claude, GPT, and other LLMs to:

• Search the web via Google (general, images, news)
• Read any webpage including JavaScript-rendered sites
• Extract YouTube transcripts automatically
• Parse documents (PDF, DOCX, PPTX)

Built for production use with caching, quality scoring, and enterprise security.

Quick Start

Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

Claude Desktop (Windows)

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

One-Click Install (MCPB)

Download the latest .mcpb bundle from GitHub Releases and double-click to install in Claude Desktop. You'll be prompted to enter your Google API credentials.

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "google-researcher": {
      "command": "npx",
      "args": ["-y", "google-researcher-mcp"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "YOUR_API_KEY_HERE",
        "GOOGLE_CUSTOM_SEARCH_ID": "YOUR_SEARCH_ID_HERE"
      }
    }
  }
}

Cline / Roo Code

Use the same JSON configuration above in your MCP settings.

Need API keys? See the API Setup Guide for step-by-step instructions to get your Google API credentials.

Local Development

git clone https://github.com/zoharbabin/google-researcher-mcp.git && cd google-researcher-mcp
npm install && npx playwright install chromium
cp .env.example .env   # Then add your Google API keys to .env
npm run dev            # Server is now running on STDIO transport

Note: This starts the server in STDIO mode, which is all you need for local AI assistant integrations. HTTP transport with OAuth is only required for web-based or multi-client setups — see Choosing a Transport.

Verify It Works

Once configured, ask your AI assistant:

"Search for the latest news about AI regulations"

The assistant will use the google_news_search tool and return current articles. If you see search results, the server is working correctly.

---

For AI Assistants (LLMs)

If you are an AI assistant reading this, here's how to use this MCP server:

Recommended Tool Selection

Example Tool Calls

// Research a topic (RECOMMENDED for most queries)
{ "name": "search_and_scrape", "arguments": { "query": "climate change effects 2024", "num_results": 5 } }

// Multi-step research with tracking (for complex investigations)
{ "name": "sequential_search", "arguments": { "searchStep": "Starting research on quantum computing", "stepNumber": 1, "totalStepsEstimate": 4, "nextStepNeeded": true } }

// Find academic papers (peer-reviewed sources with citations)
{ "name": "academic_search", "arguments": { "query": "transformer neural networks", "num_results": 5 } }

// Search patents (prior art, FTO analysis)
{ "name": "patent_search", "arguments": { "query": "machine learning optimization", "search_type": "prior_art" } }

// Get recent news
{ "name": "google_news_search", "arguments": { "query": "AI regulations", "freshness": "week" } }

// Find images
{ "name": "google_image_search", "arguments": { "query": "solar panel installation", "type": "photo" } }

// Read a specific page
{ "name": "scrape_page", "arguments": { "url": "https://example.com/article" } }

// Get YouTube transcript
{ "name": "scrape_page", "arguments": { "url": "https://www.youtube.com/watch?v=VIDEO_ID" } }

Key Behaviors

• Caching: Results are cached (30 min for search, 1 hour for scrape). Repeated queries are fast.
• Quality Scoring: search_and_scrape ranks sources by relevance, freshness, authority, and content quality.
• Graceful Failures: If some sources fail, you still get results from successful ones.
• Document Support: scrape_page auto-detects PDFs, DOCX, PPTX and extracts text.

---

Table of Contents

• For AI Assistants (LLMs)
• Available Tools
• Features
• System Architecture
• Getting Started
• Prerequisites
• Installation & Setup
• Running the Server
• Running with Docker
• Usage
• Choosing a Transport
• Client Integration
• Management API
• Security
• OAuth 2.1 Authorization
• Available Scopes
• MCP Resources
• MCP Prompts
• Testing
• Development Tools
• MCP Inspector
• Troubleshooting
• Roadmap
• Contributing
• License

Available Tools

When to Use Each Tool

Tool Reference

search_and_scrape (Recommended for research)

Searches Google and retrieves content from top results in one call. Returns quality-scored, deduplicated text with source attribution. Includes size metadata (estimatedTokens, sizeCategory, truncated) in response.

google_search

Returns ranked URLs from Google. Use when you only need links, not content.

google_image_search

Searches Google Images with filtering options.

google_news_search

Searches Google News with freshness and date sorting.

scrape_page

Extracts text from any URL. Auto-detects: web pages (static/JS), YouTube (transcript), documents (PDF/DOCX/PPTX).

sequential_search

Tracks multi-step research state. Following the sequential_thinking pattern: you do the reasoning, the tool tracks state.

academic_search

Searches academic papers via Google Custom Search API, filtered to academic sources (arXiv, PubMed, IEEE, Nature, Springer, etc.). Returns papers with pre-formatted citations.

patent_search

Searches Google Patents for prior art, freedom to operate (FTO) analysis, and patent landscaping. Returns patents with numbers, assignees, inventors, and PDF links.

Features

Core Capabilities

MCP Protocol Support

Production Ready

For detailed documentation: YouTube Transcripts · Architecture · Testing

System Architecture

graph TD
    A[MCP Client] -->|local process| B[STDIO Transport]
    A -->|network| C[HTTP+SSE Transport]

    C --> L[OAuth 2.1 + Rate Limiter]
    L --> D
    C -.->|session replay| K[Event Store]
    B --> D[McpServerMCP SDK routing + dispatch]

    D --> F[google_search]
    D --> G[scrape_page]
    D --> I[search_and_scrape]
    D --> IMG[google_image_search]
    D --> NEWS[google_news_search]
    I -.->|delegates| F
    I -.->|delegates| G
    I --> Q[Quality Scoring]

    G --> N[SSRF Validator]
    N --> S1[CheerioCrawlerstatic HTML]
    S1 -.->|insufficient content| S2[PlaywrightJS rendering]
    G --> YT[YouTube TranscriptExtractor]

    F & G & IMG & NEWS --> J[Persistent Cachememory + disk]

    D -.-> R[MCP Resources]
    D -.-> P[MCP Prompts]

    style J fill:#f9f,stroke:#333,stroke-width:2px
    style K fill:#ccf,stroke:#333,stroke-width:2px
    style L fill:#f99,stroke:#333,stroke-width:2px
    style N fill:#ff9,stroke:#333,stroke-width:2px
    style Q fill:#9f9,stroke:#333,stroke-width:2px

For a detailed explanation, see the Architecture Guide.

Getting Started

Prerequisites

• Node.js 20.0.0 or higher
• Google API Keys:
• Custom Search API Key
• Custom Search Engine ID
• Chromium (for JavaScript rendering): Installed automatically via npx playwright install chromium
• OAuth 2.1 Provider (HTTP transport only): An external authorization server (e.g., Auth0, Okta) to issue JWTs. Not needed for STDIO.

Installation & Setup

1. Clone the Repository:

git clone https://github.com/zoharbabin/google-researcher-mcp.git
    cd google-researcher-mcp

2. Install Dependencies:

npm install
    npx playwright install chromium

3. Configure Environment Variables:

cp .env.example .env

Open .env and add your Google API keys. All other variables are optional — see the comments in .env.example for detailed explanations.

Running the Server

• Development (auto-reload on file changes):

npm run dev

• Production:

npm run build
    npm start

Running with Docker

# Build the image
docker build -t google-researcher-mcp .

# Run in STDIO mode (default, for MCP clients)
docker run -i --rm --env-file .env google-researcher-mcp

# Run with HTTP transport on port 3000
# (MCP_TEST_MODE= overrides the Dockerfile default of "stdio" to enable HTTP)
docker run -d --rm --env-file .env -e MCP_TEST_MODE= -p 3000:3000 google-researcher-mcp

Docker Compose (quick HTTP transport setup):

cp .env.example .env   # Fill in your API keys
docker compose up --build
curl http://localhost:3000/health

Docker with Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "google-researcher": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "google-researcher-mcp"]
    }
  }
}

Security note: Never bake secrets into the Docker image. Always pass them at runtime via --env-file or -e flags.

Usage

Choosing a Transport

Recommendation: Use STDIO for local AI assistant integrations. Use HTTP+SSE only when you need a shared service or web application integration.

Client Integration

STDIO Client (Local Process)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/server.js"]
});
const client = new Client({ name: "my-client" });
await client.connect(transport);

// Search Google
const searchResult = await client.callTool({
  name: "google_search",
  arguments: { query: "Model Context Protocol" }
});
console.log(searchResult.content[0].text);

// Extract a YouTube transcript
const transcript = await client.callTool({
  name: "scrape_page",
  arguments: { url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
});
console.log(transcript.content[0].text);

HTTP+SSE Client (Web Application)

Requires a valid OAuth 2.1 Bearer token from your configured authorization server.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp"),
  {
    getAuthorization: async () => `Bearer YOUR_ACCESS_TOKEN`
  }
);
const client = new Client({ name: "my-client" });
await client.connect(transport);

const result = await client.callTool({
  name: "search_and_scrape",
  arguments: { query: "Model Context Protocol", num_results: 3 }
});
console.log(result.content[0].text);

Management API

Administrative and monitoring endpoints (HTTP transport only):

Security

OAuth 2.1 Authorization

All HTTP endpoints under /mcp/ (except public documentation) are protected by OAuth 2.1:

• Token Validation: JWTs are validated against your authorization server's JWKS endpoint (${OAUTH_ISSUER_URL}/.well-known/jwks.json).
• Scope Enforcement: Each tool and admin action requires a specific OAuth scope.

Configure OAUTH_ISSUER_URL and OAUTH_AUDIENCE in .env. See .env.example for details.

STDIO users: OAuth is not used for STDIO transport. You can skip all OAuth configuration.

Available Scopes

Tool Execution:

• mcp:tool:google_search:execute
• mcp:tool:google_image_search:execute
• mcp:tool:google_news_search:execute
• mcp:tool:scrape_page:execute
• mcp:tool:search_and_scrape:execute

Administration:

• mcp:admin:cache:read
• mcp:admin:cache:invalidate
• mcp:admin:cache:persist
• mcp:admin:event-store:read
• mcp:admin:config:read

MCP Resources

The server exposes state via the MCP Resources protocol. Use resources/list to discover available resources and resources/read to retrieve them.

Example (using MCP SDK):

const resources = await client.listResources();
const recentSearches = await client.readResource({ uri: "search://recent" });

MCP Prompts

Pre-built research workflow templates are available via the MCP Prompts protocol. Use prompts/list to discover prompts and prompts/get to retrieve a prompt with arguments.

Basic Research Prompts

Advanced Research Prompts

**Focus areas for technical-deep-dive:** architecture, implementation, comparison, best-practices, troubleshooting

Example (using MCP SDK):

const prompts = await client.listPrompts();

// Basic research
const research = await client.getPrompt({
  name: "comprehensive-research",
  arguments: { topic: "quantum computing", depth: "standard" }
});

// Advanced: Patent analysis
const patents = await client.getPrompt({
  name: "patent-portfolio-analysis",
  arguments: { company: "Kaltura", includeSubsidiaries: true }
});

// Advanced: Competitive analysis
const comparison = await client.getPrompt({
  name: "competitive-analysis",
  arguments: { entities: "React, Vue, Angular", aspects: "performance, learning curve, ecosystem" }
});

Testing

All NPM scripts:

For testing philosophy and structure, see the Testing Guide.

Development Tools

MCP Inspector

The MCP Inspector is a visual debugging tool for MCP servers. Use it to interactively test tools, browse resources, and verify prompts.

Run the Inspector:

npm run inspect

This opens a browser interface at http://localhost:5173 connected to the server via STDIO.

What to Expect:

Troubleshooting Inspector Issues:

• "Cannot find module" error: Run npm run build first — Inspector requires compiled JavaScript.
• Tool calls fail with API errors: Ensure GOOGLE_CUSTOM_SEARCH_API_KEY and GOOGLE_CUSTOM_SEARCH_ID are set in your .env file.
• Port 5173 in use: The Inspector UI runs on port 5173. Stop other services using that port or check if another Inspector instance is running.
• Server crashes on startup: Check that all dependencies are installed (npm install) and Playwright is set up (npx playwright install chromium).

Troubleshooting

• Server won't start: Ensure GOOGLE_CUSTOM_SEARCH_API_KEY and GOOGLE_CUSTOM_SEARCH_ID are set in .env. The server exits with a clear error if either is missing.
• Empty scrape results: The persistent cache may contain stale entries. Delete storage/persistent_cache/namespaces/scrapePage/ and restart to force fresh scrapes.
• Playwright/Chromium errors: Re-run npx playwright install chromium. On Linux, also run npx playwright install-deps chromium for system dependencies. In Docker, these are pre-installed.
• Port 3000 in use: Stop the other process (lsof -ti:3000 | xargs kill) or set PORT=3001 npm start.
• YouTube transcripts fail: Some videos have transcripts disabled by the owner. The error message includes the specific reason (e.g., TRANSCRIPT_DISABLED, VIDEO_UNAVAILABLE). See the YouTube Transcript Documentation for all error codes.
• Cache issues: Use /mcp/cache-stats to inspect cache health, or /mcp/cache-persist to force a save. See the Management API.
• OAuth errors: Verify OAUTH_ISSUER_URL and OAUTH_AUDIENCE in .env. Use /mcp/oauth-config to inspect current configuration.
• Docker health check failing: The health check hits /health on port 3000, which requires HTTP transport. In STDIO mode (MCP_TEST_MODE=stdio), the health check will fail — this is expected.

Roadmap

Feature requests and improvements are tracked as GitHub Issues. Contributions welcome.

Contributing

We welcome contributions of all kinds! Please see the Contribution Guidelines for details.

License

This project is licensed under the MIT License. See the LICENSE file for details.