Google Research MCP

🚀 Google Researcher MCP Server

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

🚀 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.

✨ Features

Core Capabilities

MCP Protocol Support

Production Ready

For detailed documentation: YouTube Transcripts · Architecture · Testing

📦 Installation Guide

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 Examples

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" } }

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);

📚 Documentation

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.

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" }
});

🔧 Technical Details

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[McpServer<br>MCP 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[CheerioCrawler<br>static HTML]
    S1 -.->|insufficient content| S2[Playwright<br>JS rendering]
    G --> YT[YouTube Transcript<br>Extractor]

    F & G & IMG & NEWS --> J[Persistent Cache<br>memory + 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.

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.

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

📄 License

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