de en es ja ko ru zh

Google Researcher MCP

Name: Google Researcher MCP
Author: zoharbabin

by zoharbabin

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Google Researcher MCP Server

npm version npm downloads GitHub stars License: MIT MCP TypeScript Tests Node.js Version

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

Features

Tool	Description
`google_search`	Web search with site, date, and language filters
`google_news_search`	News search with freshness controls
`google_image_search`	Image search with type, size, color filters
`scrape_page`	Extract content from web pages, PDFs, DOCX
`search_and_scrape`	Combined search + content extraction
`academic_search`	Papers from arXiv, PubMed, IEEE, Springer
`patent_search`	Patent search with assignee/inventor filters
YouTube	Automatic transcript extraction
`sequential_search`	Multi-step research tracking

Related MCP server: mcp-research

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

Feature	Google Researcher	Basic Web Search	Manual Research
Web Search	Yes	Yes	No
News Search	Yes	No	No
Image Search	Yes	No	No
Academic Papers	Yes	No	Yes
Patent Search	Yes	No	Yes
YouTube Transcripts	Yes	No	No
PDF Extraction	Yes	No	No
Citation Generation	Yes	No	Yes
Response Caching	Yes (30min)	No	N/A
Rate Limiting	Yes	No	N/A

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

Cursor

Add to Cursor's MCP settings (Settings > MCP):

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

Windsurf / Cline / Roo Code / Other MCP Clients

Use the same JSON configuration above in your MCP client's settings. Any MCP-compatible client that supports STDIO transport will work.

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            # Installs deps + Chromium browser automatically
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

Your Task	Use This Tool
Research a topic, answer a question	`search_and_scrape` — searches AND retrieves content in one call (recommended)
Complex multi-step investigation	`sequential_search` — tracks progress across 3+ searches, supports branching
Find academic papers	`academic_search` — searches arXiv, PubMed, IEEE with citations (APA, MLA, BibTeX)
Search patents	`patent_search` — Google Patents for prior art, FTO analysis
Find recent news	`google_news_search` — with freshness filtering and date sorting
Find images	`google_image_search` — with size/type/color filtering
Get a list of URLs only	`google_search` — when you need URLs but will process pages yourself
Read a specific URL	`scrape_page` — also extracts YouTube transcripts and parses PDF/DOCX/PPTX

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.

Available Tools

When to Use Each Tool

Tool	Best For	Use When...
`search_and_scrape`	Research (recommended)	You need to answer a question using web sources. Most efficient — searches AND retrieves content in one call. Sources are quality-scored.
`sequential_search`	Complex investigations	3+ searches needed with different angles, or research you might abandon early. Tracks progress, supports branching. You reason; it tracks state.
`academic_search`	Peer-reviewed papers	Research requiring authoritative academic sources. Returns papers with citations (APA, MLA, BibTeX), abstracts, and PDF links.
`patent_search`	Patent research	Prior art search, freedom to operate (FTO) analysis, patent landscaping. Returns patents with numbers, assignees, inventors, and PDF links.
`google_search`	Finding URLs only	You only need a list of URLs (not their content), or want to process pages yourself with custom logic.
`google_image_search`	Finding images	You need visual content — photos, illustrations, graphics. For text research, use search_and_scrape.
`google_news_search`	Current news	You need recent news articles. Use scrape_page on results to read full articles.
`scrape_page`	Reading a specific URL	You have a URL and need its content. Auto-handles YouTube transcripts and documents (PDF, DOCX, PPTX).

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.

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	3	Number of results (1-10)
`include_sources`	boolean	true	Append source URLs
`deduplicate`	boolean	true	Remove duplicate content
`max_length_per_source`	number	50KB	Max content per source in chars
`total_max_length`	number	300KB	Max total combined content in chars
`filter_by_query`	boolean	false	Filter to only paragraphs containing query keywords

`google_search`

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

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	5	Number of results (1-10)
`time_range`	string	-	`day`, `week`, `month`, `year`
`site_search`	string	-	Limit to domain
`exact_terms`	string	-	Required phrase
`exclude_terms`	string	-	Exclude words

`google_image_search`

Searches Google Images with filtering options.

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	5	Number of results (1-10)
`size`	string	-	`huge`, `large`, `medium`, `small`
`type`	string	-	`clipart`, `face`, `lineart`, `photo`, `animated`
`color_type`	string	-	`color`, `gray`, `mono`, `trans`
`file_type`	string	-	`jpg`, `gif`, `png`, `bmp`, `svg`, `webp`

`google_news_search`

Searches Google News with freshness and date sorting.

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	5	Number of results (1-10)
`freshness`	string	week	`hour`, `day`, `week`, `month`, `year`
`sort_by`	string	relevance	`relevance`, `date`
`news_source`	string	-	Filter to specific source

`scrape_page`

Extracts text from any URL. Prefers markdown via content negotiation (Accept: text/markdown) for sites that support it (Cloudflare Markdown for Agents, llms.txt). Falls back to HTML extraction (static/JS), YouTube (transcript), documents (PDF/DOCX/PPTX).

Parameter	Type	Default	Description
`url`	string	required	URL to scrape (max 2048 chars)
`max_length`	number	50KB	Maximum content length in chars. Content exceeding this is truncated at natural breakpoints.
`mode`	string	full	`full` returns content, `preview` returns metadata + structure only (useful to check size before fetching)

`sequential_search`

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

Parameter	Type	Default	Description
`searchStep`	string	required	Description of current step (1-2000 chars)
`stepNumber`	number	required	Current step number (starts at 1)
`totalStepsEstimate`	number	5	Estimated total steps (1-50)
`nextStepNeeded`	boolean	required	`true` if more steps needed, `false` when done
`source`	object	-	Source found: `{ url, summary, qualityScore? }`
`knowledgeGap`	string	-	Gap identified — what's still missing
`isRevision`	boolean	-	`true` if revising a previous step
`revisesStep`	number	-	Step number being revised
`branchId`	string	-	Identifier for branching research

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

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	5	Number of papers (1-10)
`year_from`	number	-	Filter by min publication year
`year_to`	number	-	Filter by max publication year
`source`	string	all	`all`, `arxiv`, `pubmed`, `ieee`, `nature`, `springer`
`pdf_only`	boolean	false	Only return results with PDF links
`sort_by`	string	relevance	`relevance`, `date`

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

Parameter	Type	Default	Description
`query`	string	required	Search query (1-500 chars)
`num_results`	number	5	Number of results (1-10)
`search_type`	string	prior_art	`prior_art`, `specific`, `landscape`
`patent_office`	string	all	`all`, `US`, `EP`, `WO`, `JP`, `CN`, `KR`
`assignee`	string	-	Filter by assignee/company
`inventor`	string	-	Filter by inventor name
`cpc_code`	string	-	Filter by CPC classification code
`year_from`	number	-	Filter by min year
`year_to`	number	-	Filter by max year

Features

Core Capabilities

Feature	Description
Web Scraping	Fast static HTML + automatic Playwright fallback for JavaScript-rendered pages
YouTube Transcripts	Robust extraction with retry logic and 10 classified error types
Document Parsing	Auto-detects and extracts text from PDF, DOCX, PPTX
Quality Scoring	Sources ranked by relevance (35%), freshness (20%), authority (25%), content quality (20%)

MCP Protocol Support

Feature	Description
Tools	8 tools: `search_and_scrape`, `google_search`, `google_image_search`, `google_news_search`, `scrape_page`, `sequential_search`, `academic_search`, `patent_search`
Resources	Expose server state: `stats://tools` (per-tool metrics), `stats://cache`, `search://recent`, `config://server`
Prompts	Pre-built templates: `comprehensive-research`, `fact-check`, `summarize-url`, `news-briefing`
Annotations	Content tagged with audience, priority, and timestamps

Production Ready

Feature	Description
Caching	Two-layer (memory + disk) with per-tool namespaces, reduces API costs
Dual Transport	STDIO for local clients, HTTP+SSE for web apps
Security	OAuth 2.1, SSRF protection, granular scopes
Resilience	Circuit breaker, timeouts, graceful degradation
Monitoring	Admin endpoints for cache stats, event store, health checks

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

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 during npm install via postinstall hook
OAuth 2.1 Provider (HTTP transport only): An external authorization server (e.g., Auth0, Okta) to issue JWTs. Not needed for STDIO.

Installation & Setup

Clone the Repository:

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

Install Dependencies (includes Chromium browser automatically):
```
npm install
```
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

	STDIO	HTTP+SSE
Best for	Local MCP clients (Claude Code, Cline, Roo Code)	Web apps, multi-client setups, remote access
Auth	None needed (process-level isolation)	OAuth 2.1 Bearer tokens required
Setup	Zero config — just provide API keys	Requires OAuth provider (Auth0, Okta, etc.)
Scaling	One server per client process	Single server, many concurrent clients

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

Method	Endpoint	Description	Auth
`GET`	`/health`	Server health check (status, version, uptime)	Public
`GET`	`/version`	Server version and runtime info	Public
`GET`	`/mcp/cache-stats`	Cache performance statistics	`mcp:admin:cache:read`
`GET`	`/mcp/event-store-stats`	Event store usage statistics	`mcp:admin:event-store:read`
`POST`	`/mcp/cache-invalidate`	Clear specific cache entries	`mcp:admin:cache:invalidate`
`POST`	`/mcp/cache-persist`	Force cache save to disk	`mcp:admin:cache:persist`
`GET`	`/mcp/oauth-config`	Current OAuth configuration	`mcp:admin:config:read`
`GET`	`/mcp/oauth-scopes`	OAuth scopes documentation	Public
`GET`	`/mcp/oauth-token-info`	Token details	Authenticated

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.

URI	Description
`search://recent`	Last 20 search queries with timestamps and result counts
`config://server`	Server configuration (version, start time, transport mode)
`stats://cache`	Cache statistics (hit rate, entry count, memory usage)
`stats://events`	Event store statistics (event count, storage size)

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

Prompt	Arguments	Description
`comprehensive-research`	`topic`, `depth` (quick/standard/deep)	Multi-source research on a topic
`fact-check`	`claim`, `sources` (number)	Verify a claim against multiple sources
`summarize-url`	`url`, `format` (brief/detailed/bullets)	Summarize content from a single URL
`news-briefing`	`topic`, `timeRange` (day/week/month)	Get current news summary on a topic

Advanced Research Prompts

Prompt	Arguments	Description
`patent-portfolio-analysis`	`company`, `includeSubsidiaries`	Analyze a company's patent holdings
`competitive-analysis`	`entities` (comma-separated), `aspects`	Compare companies/products
`literature-review`	`topic`, `yearFrom`, `sources`	Academic literature synthesis
`technical-deep-dive`	`technology`, `focusArea`	In-depth technical investigation

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

Script	Description
`npm test`	Run all unit/component tests (Jest)
`npm run test:e2e`	Full end-to-end suite (STDIO + HTTP + YouTube)
`npm run test:coverage`	Generate code coverage report
`npm run test:e2e:stdio`	STDIO transport E2E only
`npm run test:e2e:sse`	HTTP transport E2E only
`npm run test:e2e:youtube`	YouTube transcript E2E only

All NPM scripts:

Script	Description
`npm start`	Run the built server (production)
`npm run dev`	Start with live-reload (development)
`npm run build`	Compile TypeScript to `dist/`
`npm run inspect`	Open MCP Inspector for interactive debugging

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:

Primitive	Count	Items
Tools	8	`google_search`, `google_image_search`, `google_news_search`, `scrape_page`, `search_and_scrape`, `sequential_search`, `academic_search`, `patent_search`
Resources	6	`search://recent`, `config://server`, `stats://cache`, `stats://events`, `search://session/current`, `stats://resources`
Prompts	8	`comprehensive-research`, `fact-check`, `summarize-url`, `news-briefing`, `patent-portfolio-analysis`, `competitive-analysis`, `literature-review`, `technical-deep-dive`

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). Chromium is installed automatically via the postinstall hook.

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: Chromium is installed automatically during npm install. If it failed, re-run npx playwright install chromium. On Linux, also run npx playwright install-deps chromium for system dependencies. In Docker, these are pre-installed. If the browser is missing at runtime, scrape_page returns a clear error message instead of crashing.
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.

Star History

If you find this project useful, please consider giving it a star — it helps others discover it.

License

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

Available Tools

8 tools

academic_searchAcademic Paper SearchA

Read-only

Search academic papers using Google Custom Search API.

When to use:

Finding peer-reviewed, authoritative sources
Research requiring citations and references
Technical/scientific topics and literature reviews

Features:

Paper titles, authors, abstracts
Publication years and venues
Direct PDF links (when available)
Pre-formatted citations (APA, MLA, BibTeX)

Academic sources: arXiv, PubMed, IEEE, Nature, Springer, ResearchGate, JSTOR, and more.

Caching: Results cached for 30 minutes.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Search query for academic papers
`num_results`	No	Number of papers to return (1-10, default: 5)
`year_from`	No	Only include papers published in or after this year
`year_to`	No	Only include papers published in or before this year
`source`	No	Limit search to specific academic source (default: all sources)	all
`pdf_only`	No	Only return results with PDF links
`sort_by`	No	Sort by relevance or publication date (most recent first)	relevance

Output Schema

ParametersJSON Schema

Name	Required	Description
`papers`	Yes	List of academic papers
`query`	Yes	The search query that was executed
`totalResults`	Yes	Total papers matching query
`resultCount`	Yes	Number of papers returned
`source`	Yes	Data source

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint and openWorldHint. The description adds valuable context: caching for 30 minutes, list of academic sources, and features like citations and PDF links, which go beyond annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear headings (When to use, Features, etc.) and is concise at around 80 words, covering key points without verbosity. Slightly more could be trimmed, but it's effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers use cases, features, sources, and caching; with an output schema present, it does not need to detail return values. It is complete for a search tool of moderate complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since input schema provides 100% description coverage for all 7 parameters, the description adds no further parameter details. Baseline 3 is appropriate as the schema already explains each parameter well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches academic papers using Google Custom Search API. It distinguishes itself from siblings like google_search and patent_search by specifying academic sources and use cases, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'When to use' section explicitly lists appropriate contexts like peer-reviewed research and literature reviews. However, it does not specify when not to use this tool or suggest alternatives among siblings, so it lacks full guidance on exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

google_image_searchGoogle Image SearchA

Read-only

Search for images using Google Custom Search API. Returns image URLs, thumbnails, dimensions, and source page URLs.

When to use:

Finding visual content — photos, illustrations, graphics, diagrams
Need specific image formats, sizes, or color types

Key parameters:

size: huge, large, medium, small
type: clipart, face, lineart, photo, animated
color_type: color, gray, mono, trans (transparent)
file_type: jpg, gif, png, svg, webp

Caching: Results cached for 30 minutes.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The image search query
`num_results`	No	Number of image results to return
`size`	No	Filter by image size
`type`	No	Filter by image type
`color_type`	No	Filter by color type
`dominant_color`	No	Filter by dominant color
`file_type`	No	Filter by file format
`safe`	No	Safe search level

Output Schema

ParametersJSON Schema

Name	Required	Description
`images`	Yes	List of image results
`query`	Yes	The search query that was executed
`resultCount`	Yes	Number of images found

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds behavioral details: results are cached for 30 minutes and it uses the Google Custom Search API, which is consistent and adds value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with clear sections (purpose, when to use, key parameters, caching). Every sentence adds value, and the structure is front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (8 parameters, high schema coverage, output schema exists, annotations present), the description is complete. It covers API, filtering options, and caching, leaving no obvious gaps for an AI agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions. The description goes further by summarizing key parameters (size, type, color_type, file_type) with their enum values, making it easier for an agent to understand relevant filters at a glance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for images using Google Custom Search API and specifies what it returns (image URLs, thumbnails, dimensions, source page URLs). It effectively distinguishes this from sibling tools like google_search (general web search) and google_news_search (news).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a 'When to use' section listing use cases like finding visual content and needing specific formats/sizes/colors. While it implies alternatives by context, it does not explicitly name sibling tools or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

google_news_searchGoogle News SearchA

Read-only

Search for recent news articles with freshness filters and date sorting.

When to use:

Current events, breaking news, time-sensitive topics
Need headlines and snippets from news sources
Want to restrict by publication date

When to use scrape_page instead:

You need the full article content

Key parameters:

freshness: hour, day, week, month, year (default: week)
sort_by: relevance or date
news_source: Restrict to specific domain (e.g., 'bbc.com')

Caching: Results cached for 30 minutes.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	The news search query
`num_results`	No	Number of news results to return
`freshness`	No	How recent the news should be	week
`sort_by`	No	Sort order: by relevance or by date (most recent first)	relevance
`news_source`	No	Restrict to a specific news source domain

Output Schema

ParametersJSON Schema

Name	Required	Description
`articles`	Yes	List of news articles
`query`	Yes	The search query that was executed
`resultCount`	Yes	Number of articles found
`freshness`	Yes	Freshness filter that was applied
`sortedBy`	Yes	Sort order used

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint. Description adds caching (30 min) and implies results are headlines/snippets, but could mention output format or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and bullet points, front-loaded with purpose, no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given output schema exists, description is complete: covers purpose, usage guidelines, key parameters, and caching. No gaps for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 5 parameters with descriptions (100% coverage). Description adds value by listing key params with defaults and usage hints, exceeding baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool searches for recent news articles with freshness and date sorting, distinguishing it from siblings like general web search or image search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when-to-use (current events, breaking news) and when-to-use-alternative (scrape_page for full article), plus caching info.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

google_searchGoogle SearchA

Read-only

Search the web using Google Custom Search API. Returns a list of URLs with titles and snippets.

When to use:

You need URLs to process yourself (e.g., selective scraping)
You only need links without full content
You want to filter/choose which URLs to scrape

When to use search_and_scrape instead:

You need actual page content for research
You want content from multiple sources combined

Caching: Results cached for 30 minutes.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The search query string. Use natural language or specific keywords for better results. More specific queries yield better results and more relevant sources.
`num_results`	No	Number of search results to return (1-10). Higher numbers increase processing time and API costs. Use 3-5 for quick research, 8-10 for comprehensive coverage.
`time_range`	No	Restrict results to a recent time range. 'day' = last 24 hours, 'week' = last 7 days, 'month' = last 30 days, 'year' = last 365 days. Omit for no time restriction.
`site_search`	No	Limit results to a specific site (e.g., 'github.com', 'stackoverflow.com'). Useful for domain-specific research.
`site_search_filter`	No	Whether to include or exclude results from site_search. 'include' (default) shows only results from the site, 'exclude' removes results from the site.
`exact_terms`	No	Required exact phrase that must appear in all results. Useful for finding specific quotes or technical terms.
`exclude_terms`	No	Terms to exclude from search results. Useful for filtering out irrelevant topics. Separate multiple terms with spaces.
`language`	No	Restrict results to a specific language. Format: 'lang_XX' where XX is ISO 639-1 code (e.g., 'lang_en' for English, 'lang_es' for Spanish, 'lang_fr' for French).
`country`	No	Restrict results to a specific country. Format: 'countryXX' where XX is ISO 3166-1 alpha-2 code (e.g., 'countryUS' for United States, 'countryGB' for United Kingdom).
`safe`	No	Safe search filtering level. 'off' = no filtering, 'medium' = moderate filtering, 'high' = strict filtering. Defaults to Google's account settings if omitted.

Output Schema

ParametersJSON Schema

Name	Required	Description
`urls`	Yes	List of URLs returned by the search
`query`	Yes	The search query that was executed
`resultCount`	Yes	Number of URLs found

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true (safe read) and openWorldHint=true (variable results). The description adds value by specifying that results are cached for 30 minutes and that only URLs/titles/snippets are returned, not full content. This complements the annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, starting with a clear action statement, followed by bullet-point lists for usage guidance, and a brief caching note. Every sentence serves a purpose, and the formatting is optimized for AI readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, sibling tools, output schema present), the description covers purpose, usage guidelines, caching behavior, and explicit alternative tool identification. It leverages the output schema to avoid redundant return value explanations, making it complete for informed tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all 10 parameters with detailed descriptions (100% coverage). The tool description does not add any additional parameter-specific information beyond what the schema provides. With full schema coverage, a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search the web using Google Custom Search API') and return format ('list of URLs with titles and snippets'). It distinguishes the tool from its sibling 'search_and_scrape' by specifying when to use each, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit 'When to use' and 'When to use search_and_scrape instead' sections, providing clear guidance on when to select this tool over its primary alternative. Caching behavior is also noted, offering comprehensive usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

patent_searchPatent SearchA

Read-only

Search patents using Google Custom Search API (site:patents.google.com).

When to use:

Prior art search before filing
Freedom to operate (FTO) analysis
Patent landscaping and competitive intelligence
Tracking innovation in specific domains

Features:

Patent titles, numbers, abstracts
Inventors and assignees
Filing and publication dates
Direct links to Google Patents and PDFs
Filter by patent office (USPTO, EPO, WIPO, JPO, CNIPA, KIPO)
Assignee search with automatic name variations

Important limitation: Google Custom Search doesn't index ALL patents. For comprehensive company patent research:

Use this tool for initial discovery with technology keywords
Use scrape_page on patents.google.com/?assignee=CompanyName for more complete results
Try multiple variations: company names without spaces, previous names, inventor names
Note that patents may be assigned to parent companies or subsidiaries

Search types:

prior_art: Find related existing patents
specific: Look up specific patent(s)
landscape: Broad overview of a technology area

Caching: Results cached for 30 minutes.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	Patent search query (keywords, patent number, inventor, assignee). TIP: Try company name WITHOUT spaces (e.g., "raptmedia" instead of "Rapt Media") and try previous company names.
`num_results`	No	Number of patents to return (1-10, default: 5)
`search_type`	No	Search type: prior_art (find related patents), specific (exact patent), landscape (broad overview)	prior_art
`patent_office`	No	Filter by patent office (US=USPTO, EP=EPO, WO=WIPO, JP=JPO, CN=CNIPA, KR=KIPO)
`assignee`	No	Company name to search for. Automatically tries variations (with/without spaces, Inc/Corp). For better results, also try previous company names in the query.
`inventor`	No	Inventor name to search for (exact phrase match)
`cpc_code`	No	CPC classification code to search for (e.g., G06F, H04L)
`year_from`	No	Filter patents from this year onwards
`year_to`	No	Filter patents up to this year

Output Schema

ParametersJSON Schema

Name	Required	Description
`patents`	Yes	List of patent results
`query`	Yes	The search query that was executed
`totalResults`	Yes	Total patents matching query
`resultCount`	Yes	Number of patents returned
`searchType`	Yes	Type of patent search
`source`	Yes	Data source

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context beyond that, such as 30-minute caching, incomplete indexing of Google Custom Search, and automatic assignee name variations, which helps the agent understand the tool's behavior and limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clearly separated sections (When to use, Features, Limitation, Search types, Caching). It is concise yet comprehensive, with every section adding unique value. No unnecessary repetition or vague statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, 1 required), 100% schema coverage, presence of output schema, and the detailed description covering limitations and advanced usage scenarios, the definition is complete. The agent has all necessary information to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for all 9 parameters. The description further enriches parameter meaning with tips (e.g., company name without spaces, previous names), search type definitions, and assignee auto-variations. While the schema already documents parameters, the description adds contextual guidance that improves agent understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches patents using Google Custom Search API, with specific use cases and search types. It distinguishes itself from sibling tools like google_search and scrape_page by focusing exclusively on patent data and providing patent-specific features and limitations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists when to use (prior art, FTO, landscaping) and provides important limitations and alternative tools (scrape_page for comprehensive company research). It also includes caching information and tips for better results, guiding the agent on effective usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scrape_pageScrape Page (+ YouTube, PDF, DOCX, PPTX)A

Read-only

Extract text content from a URL. Automatically handles: web pages (static + JavaScript-rendered), YouTube videos (extracts transcript), and documents (PDF, DOCX, PPTX).

When to use:

You already have a specific URL to extract content from
Need content from YouTube videos, PDFs, or Office documents
Want to check page structure before fetching full content (preview mode)

When to use search_and_scrape instead:

Researching a topic across multiple sources

Content size control:

max_length: Limit response size (default: server max of 50KB)
mode: 'full' returns content, 'preview' returns metadata + structure only

Preview mode benefits:

Check content size before fetching full content
Get page structure (headings) to decide which sections to read
Avoid context exhaustion with very large pages

Caching: Results cached for 1 hour.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	The URL to scrape. Supports: web pages (static HTML and JavaScript-rendered SPAs), YouTube videos (extracts transcript automatically), and documents (PDF, DOCX, PPTX - extracts text content).
`max_length`	No	Maximum content length in characters. Content exceeding this will be truncated at natural breakpoints. Default: server max (50KB).
`mode`	No	'full' returns content (default), 'preview' returns metadata and structure without full content.	full

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes	The URL that was scraped
`content`	Yes	The extracted text content from the page
`contentType`	Yes	The type of content that was extracted
`contentLength`	Yes	Length of the extracted content in characters
`truncated`	Yes	Whether the content was truncated due to size limits
`estimatedTokens`	Yes	Estimated token count (~4 chars/token)
`sizeCategory`	Yes	Size category based on content length
`originalLength`	No	Original content length before truncation
`metadata`	No	Additional metadata for documents
`citation`	No	Citation information with metadata and formatted strings
`preview`	No	Content preview with structure (when mode=preview)

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses caching (1 hour), preview vs full mode behavior, and automatic handling of JS-rendered pages. Contradicts no annotations; adds context beyond readOnly and openWorld hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, front-loaded purpose, and no fluff. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (multiple content types, modes, caching) and presence of output schema, the description covers all needed aspects for correct tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds useful details like default max_length (50KB) and preview mode benefits, slightly exceeding the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts text content from URLs and lists supported types (web pages, YouTube, PDF, DOCX, PPTX). It distinguishes from siblings like search_and_scrape by focusing on single URL extraction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (specific URL, YouTube/documents, preview) and when not (use search_and_scrape for multi-source research). This helps the agent choose correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_and_scrapeSearch and ScrapeA

Read-only

Search Google AND retrieve content from top results in one call. Returns combined, deduplicated content with source attribution.

When to use:

Primary tool for answering questions that need web research
Need content from multiple sources combined
More efficient than calling google_search + scrape_page separately

When to use other tools instead:

google_search: When you only need URLs without content
scrape_page: When you already have a specific URL

Content size control:

max_length_per_source: Limit content per source (default: 50KB)
total_max_length: Limit total combined content (default: 300KB)
filter_by_query: Only include paragraphs containing query keywords

Caching: Search results cached for 30 minutes, scraped pages for 1 hour.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Your research question or topic. Be specific for better results. Example: 'Python async best practices 2024' rather than just 'Python'.
`num_results`	No	Number of sources to fetch (1-10). Default 3 is good for most queries. Use 5-8 for comprehensive research, 1-2 for quick factual lookups.
`include_sources`	No	Include source URLs at the end for citation. Default true - recommended for transparency.
`deduplicate`	No	Remove duplicate content across sources. Default true - recommended to reduce noise when sources quote each other.
`max_length_per_source`	No	Maximum content length per source in characters. Default: 50KB.
`total_max_length`	No	Maximum total combined content length. Default: 300KB.
`filter_by_query`	No	Filter to only include paragraphs containing query keywords. Reduces noise but may exclude relevant context.

Output Schema

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The search query that was executed
`sources`	Yes	List of sources that were processed
`combinedContent`	Yes	Combined and optionally deduplicated content from all sources
`summary`	Yes	Summary statistics for the operation
`sizeMetadata`	Yes	Size information for the combined content

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark readOnlyHint and openWorldHint; description adds: combined deduplicated content with attribution, caching (30min search, 1hr scraped), content size limits. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with markdown sections (When to use, alternatives, content control, caching). Every sentence is informative, no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, 100% schema coverage, and output schema, description covers all key aspects: purpose, usage, parameters, caching, and behavior. Complete for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100% with detailed descriptions. Description adds default values, usage examples, and behavioral context for each parameter, exceeding baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it searches Google and retrieves content from top results. Distinguished from siblings: google_search (URLs only) and scrape_page (specific URL).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides when to use (web research, multiple sources, efficiency) and when to use alternatives (only URLs, specific URL). Includes content size control and caching guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sequential_searchSequential SearchA

Track multi-step research progress across multiple API calls.

When to use:

Complex investigations requiring 3+ searches with different angles
Research you might abandon early (tracks partial progress)
Investigations where you need to show reasoning steps
Research with branching paths to explore alternatives

When to use search_and_scrape instead:

Simple queries that need content from multiple sources in one call

Key principle: You do the reasoning; this tool tracks state. It persists across API calls so you can build on previous steps.

Example flow:

Start: sequential_search(searchStep: "Starting research on X", stepNumber: 1, nextStepNeeded: true)
Search: search_and_scrape("topic")
Record: sequential_search(searchStep: "Found Y, need Z", stepNumber: 2, source: {...}, nextStepNeeded: true)
Complete: sequential_search(searchStep: "Research complete", stepNumber: 3, nextStepNeeded: false)

ParametersJSON Schema

Name	Required	Description
`searchStep`	Yes	Description of what you searched or found in this step
`stepNumber`	Yes	Current step number (starts at 1)
`totalStepsEstimate`	No	Estimated total steps needed (can be adjusted as you go)
`nextStepNeeded`	Yes	Set to true if more research steps are needed, false when done
`source`	No	Source found in this step (if any)
`knowledgeGap`	No	Knowledge gap identified - what information is still missing
`isRevision`	No	Set to true if this step revises previous thinking
`revisesStep`	No	Step number being revised (required if isRevision is true)
`branchFromStep`	No	Step number to branch from (for exploring alternatives)
`branchId`	No	Identifier for this branch of research
`sessionId`	No	Session ID to continue (optional - uses current session if omitted)

Output Schema

ParametersJSON Schema

Name	Required	Description
`sessionId`	Yes	Unique session identifier
`currentStep`	Yes	Current step number
`totalStepsEstimate`	Yes	Estimated total steps
`isComplete`	Yes	Whether research is marked as complete
`sourceCount`	Yes	Number of sources collected so far
`openGapsCount`	Yes	Number of unresolved knowledge gaps
`stateSummary`	Yes	Human-readable summary of research state
`sources`	No	All sources collected (included when complete)
`gaps`	No	All knowledge gaps (included when complete)

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains that the tool tracks state across API calls and provides an example flow. Annotations are minimal (readOnlyHint false), but the description adds context about persistence and step-by-step progress. It does not mention potential side effects like data retention limits, but overall it is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (When to use, When not to use, Key principle, Example flow). Every sentence provides value and it is front-loaded with the main purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (11 parameters, nested objects, output schema), the description covers all necessary aspects: workflow, usage rules, parameter roles via example, and persistence. The output schema exists, so return values are documented elsewhere. The description is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the input schema already explains parameters. The description adds value through the example flow and key principle, showing how parameters like searchStep and stepNumber are used in sequence, which helps the agent understand the tool's usage pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Track multi-step research progress across multiple API calls' which clearly states the tool's verb and resource. It differentiates from sibling tools like search_and_scrape by specifying when to use each.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists when to use (complex investigations, 3+ searches, early abandonment, branching) and when to use an alternative (search_and_scrape for simple queries). This provides clear guidance on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

8 tool updatesv6.3.1May 7, 2026
- First observedacademic_search
- First observedgoogle_image_search
- First observedgoogle_news_search
- First observedgoogle_search
- First observedpatent_search
- First observedscrape_page
- First observedsearch_and_scrape
- First observedsequential_search

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored 2026-05-17 08:05 across 8 tools

Disambiguation5/5

Each tool targets a distinct type of content or action: academic papers, images, news, general web, patents, page scraping, combined search+scrape, and progress tracking. Their purposes are clearly differentiated by name and description, leaving little ambiguity.

Naming Consistency4/5

Most tools follow a descriptive pattern (e.g., academic_search, google_news_search, patent_search), but there are minor inconsistencies: scrape_page and search_and_scrape break the 'type_search' pattern, and sequential_search uses an adjective. Overall, names are clear and mostly consistent.

Tool Count5/5

With 8 tools, the server is well-scoped for a research assistant. It covers essential search types and content extraction without being overwhelming. Each tool adds distinct value, and the count feels appropriate for the domain.

Completeness5/5

The tool set covers the major facets of web research: various search verticals (web, academic, news, images, patents), page scraping, combined search+scrape, and even a research progress tracker. There are no obvious gaps; it provides a comprehensive workflow.

Maintenance

ActivityInactive

ResponsivenessWithin a week

Resources

Need Help?

Related Servers

Related MCP Connectors

Sofya A
co.sofya
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
Search Browser Automation Web Scraping
422
Siftwright web data A
com.siftwright
Web data for agents: YouTube transcripts, screenshots, Google News, WHOIS, jobs, tech stack, more.
Browser Automation Web Scraping Search
91
Research MCP ServerOAuth
io.damistudio
Fourteen research tools, from arXiv to SEC filings. Tool calls are billed to your Apify account.
Research & Data Documentation Access Search
1
neo-x402-mcp B
io.github.atakanelik34
8-tool AI web intelligence suite: search, scrape, screenshot, SEO, docs, crypto, code.
Search Web Scraping Browser Automation
2

Related MCP Servers

Research Powerpack MCP
Search Web Scraping RAG Systems
yigitkonur
F
license
A
quality
Not graded
maintenance
Enables AI assistants to perform comprehensive research by searching Google, mining Reddit discussions, scraping web content with JS rendering, and synthesizing findings with citations into structured context.
Updated 8 months ago (2026-03-03 15:47 UTC)
5
165 npm
3
-
mcp-research
Browser Automation Search Web Scraping
MABAAM
A
license
A
quality
C
maintenance
Enables AI assistants to perform comprehensive web research through tiered search, secure URL fetching with markdown conversion, and automated multi-source synthesis pipelines. Provides read-only tools with configurable caching, SSRF protection, and optional LLM-powered summarization for search results and content analysis.
Updated 6 months ago (2026-04-09 14:01 UTC)
8
1
MIT
sofya-mcpofficial
Browser Automation Web Scraping Search
sofya-co
A
license
A
quality
C
maintenance
Web tools for AI agents. Search the web for full page content, fetch URLs as clean markdown including PDFs, extract structured data from a page with a prompt, and run multi-source deep research that returns a cited report.
Updated 16 days ago (2026-10-05 19:04 UTC)
4
2
MIT
agentic-research
RAG Systems Autonomous Agents Search
abhilash2429
F
license
Not graded
quality
B
maintenance
Enables AI agents to perform deep web research by searching, fetching, chunking, retrieving, and synthesizing cited answers from exact source passages via a deep_research tool.
Updated 2 months ago (2026-08-22 18:18 UTC)
-

Google Researcher MCP Server

Features

Use Cases

Comparison with Alternatives

Quick Start

Claude Desktop (macOS)

Claude Desktop (Windows)

One-Click Install (MCPB)

Claude Code

Cursor

Windsurf / Cline / Roo Code / Other MCP Clients

Local Development

Verify It Works

For AI Assistants (LLMs)

Recommended Tool Selection

Example Tool Calls

Key Behaviors

Table of Contents

Available Tools

When to Use Each Tool

Tool Reference

search_and_scrape (Recommended for research)

google_search

google_image_search

google_news_search

scrape_page

sequential_search

academic_search

patent_search

Features

Core Capabilities

MCP Protocol Support

Production Ready

System Architecture

Getting Started

Prerequisites

Installation & Setup

Running the Server

Running with Docker

Usage

Choosing a Transport

Client Integration

STDIO Client (Local Process)

HTTP+SSE Client (Web Application)

Management API

Security

OAuth 2.1 Authorization

Available Scopes

MCP Resources

MCP Prompts

Basic Research Prompts

Advanced Research Prompts

Testing

Development Tools

MCP Inspector

Troubleshooting

Roadmap

Contributing

Star History

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

sofya-mcpofficial

Appeared in Searches

`search_and_scrape` (Recommended for research)

`google_search`

`google_image_search`

`google_news_search`

`scrape_page`

`sequential_search`

`academic_search`

`patent_search`