Skip to main content
Glama
google-scholar-search-mcp

google-scholar-search-mcp

by LWaetzig

google-scholar-search-mcp

An MCP (Model Context Protocol) server for searching Google Scholar, built for AI assistants and automation workflows that need papers, citations, and BibTeX entries.

Table of Contents

  1. Features

  2. Installation

  3. Configuration

  4. Usage

  5. Examples

  6. Rate Limiting

  7. Troubleshooting

  8. Contributing

Related MCP server: Scholar MCP

Features

  • Paper Search: Query Google Scholar by keyword with filtering, sorting, and paging (offset / next_offset, also for citations)

  • Citation Tracking: Retrieve papers that cite a given work

  • ID Lookups: Fetch details, citations and BibTeX by scholar_id instead of a fragile title search

  • Paper Details: Get full metadata, citations-per-year graphs, and public access info

  • BibTeX Export: Generate citation entries in BibTeX format

  • Bulk Search: Batch search multiple queries with automatic rate limiting

  • Caching: Repeated lookups are answered from memory (no delay, no request to Scholar)

  • Rate Limiting: Every HTTP request to Scholar is spaced by a random delay (also the several requests inside one tool call), to avoid being blocked

  • Proxy Support: Optional proxy configuration (free, single, or ScraperAPI)

Installation

Requirements

  • Python 3.12 or later

uv tool install google-scholar-search-mcp   # or: pip install google-scholar-search-mcp
google-scholar-mcp setup

setup registers the server with Claude Desktop (claude_desktop_config.json) and Claude Code (claude mcp add --scope user), plus Cursor (~/.cursor/mcp.json), Windsurf and Gemini CLI when installed, and downloads the agent skill into ~/.claude/skills/google-scholar-mcp/. Existing entries in your config are preserved. Skip parts with --no-claude-desktop, --no-claude-code or --no-skill. Restart your client afterwards.

Try it without installing: uvx google-scholar-search-mcp setup.

Command

Purpose

google-scholar-mcp / serve

Run the MCP server over stdio

google-scholar-mcp doctor

Check whether Google Scholar answers this client (one request; exit code 1 if blocked)

google-scholar-mcp set-cookies

Save Scholar cookies and User-Agent copied from the browser's developer tools (clipboard or --stdin), then run doctor

google-scholar-mcp setup

Configure clients and install the skill

google-scholar-mcp install-skill [--target T]... [--root D] [--force]

Download the skill into every detected agent in the project (falls back to the bundled copy offline)

install-skill detects which agents the current project uses and writes to each; name targets explicitly with --target. It never overwrites a differing file without --force, and only edits the marked block in shared files.

Target

Detected by

Written to

claude-user

always

~/.claude/skills/google-scholar-mcp/SKILL.md

claude

.claude/

.claude/skills/google-scholar-mcp/SKILL.md

cursor

.cursor/

.cursor/rules/google-scholar-mcp.mdc

windsurf

.windsurf/

.windsurf/rules/google-scholar-mcp.md

agents (Codex, Amp, OpenCode, Jules, …)

AGENTS.md

pointer block in AGENTS.md + .agents/skills/google-scholar-mcp/SKILL.md

gemini

GEMINI.md or .gemini/

pointer block in GEMINI.md + .agents/skills/google-scholar-mcp/SKILL.md

Codex stores MCP servers in TOML (~/.codex/config.toml), which setup does not edit; its skill is covered by the agents target.

Build from Source

git clone https://github.com/LWaetzig/google-scholar-search-mcp.git
cd google-scholar-search-mcp
pip install -e .

Note: This server uses the scholarly library to access Google Scholar. Respect Google's Terms of Service and use rate limiting appropriately to avoid being blocked.

Configuration

Configure the MCP server via environment variables:

Variable

Default

Description

GS_MIN_DELAY

5.0

Minimum seconds between two HTTP requests to Scholar. A tool call that needs several requests (e.g. a title lookup: search, then fetch) takes that many delays

GS_MAX_DELAY

15.0

Maximum seconds between requests

GS_MAX_RETRIES

3

Number of retries on failure

GS_PROXY_TYPE

none

Proxy mode: none, free, single, scraperapi

GS_PROXY_HTTP

—

HTTP proxy URL (for single mode)

GS_PROXY_HTTPS

—

HTTPS proxy URL (for single mode)

GS_SCRAPERAPI_KEY

—

ScraperAPI key (for scraperapi mode)

GS_TIMEOUT

30

Request timeout in seconds

GS_COOKIES_FILE

—

File containing your browser's Cookie header for Scholar (see Using browser cookies); preferred over GS_COOKIES

GS_COOKIES

—

Same, as a value (ends up in client config files; prefer the file)

GS_USER_AGENT

—

User-Agent of the browser the cookies came from; must match

GS_BLOCK_COOLDOWN

900

Seconds to stop querying Scholar after it blocked the client (bot check / sign-in redirect); calls fail fast with [BLOCKED] meanwhile. 0 disables

GS_CACHE_TTL

3600

Seconds a successful result is reused from memory (0 disables the cache)

GS_CACHE_SIZE

256

Most cached results kept; the least recently used is dropped first

GS_SKILL_URL

GitHub raw URL of SKILL.md

URL advertised to agents in the server instructions; set to an empty string to omit

Agent skill

The package ships SKILL.md, which tells an agent when and how to use the tools (tool choice, rate limits, error handling). google-scholar-mcp setup (or install-skill) downloads it from GS_SKILL_URL into ~/.claude/skills/google-scholar-mcp/, falling back to the bundled copy if the download fails. The server also advertises the URL in the MCP server instructions.

Proxy Configuration Examples

No Proxy (Default)

export GS_PROXY_TYPE=none

Free Proxy

export GS_PROXY_TYPE=free

Single Proxy

export GS_PROXY_TYPE=single
export GS_PROXY_HTTP=http://proxy.example.com:8080
export GS_PROXY_HTTPS=https://proxy.example.com:8080

ScraperAPI

export GS_PROXY_TYPE=scraperapi
export GS_SCRAPERAPI_KEY=your_key_here

Usage

Detailed documentation about single tools can be found here

Integration with Claude Desktop

Add the server to your Claude Desktop configuration:

Platform

Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Add the google-scholar entry under mcpServers:

{
  "mcpServers": {
    "google-scholar": {
      "command": "google-scholar-mcp",
      "env": {
        "GS_MIN_DELAY": "5.0",
        "GS_MAX_DELAY": "15.0",
        "GS_PROXY_TYPE": "none"
      }
    }
  }
}

After updating the config, restart Claude Desktop. The Google Scholar tools will appear in the MCP Tools panel.

Integration with Other MCP Clients

Any MCP client (e.g., Cline, Continue, or custom tools) can use this server. Configure the connection to:

Command: google-scholar-mcp
Transport: stdio

Rate Limiting

The server automatically enforces rate limiting between requests to avoid overloading Google Scholar's servers:

  • Min Delay (default 5s): Minimum wait between consecutive requests

  • Max Delay (default 15s): Maximum wait (randomized to avoid patterns)

  • Max Retries (default 3): Retry failed requests up to this many times

These settings help prevent being blocked by Google Scholar. Adjust via environment variables if needed:

export GS_MIN_DELAY=3.0
export GS_MAX_DELAY=10.0
export GS_MAX_RETRIES=5

⚠️ IP Blocking Warning

If you exceed Google Scholar's rate limits despite the rate limiter:

  • Your IP may be temporarily blocked (usually 24-48 hours)

  • All requests will fail with connection errors or 429 responses

  • Blocked IPs cannot make requests even with valid proxies on the same IP range

  • Repeated violations may trigger permanent blocks or require CAPTCHA solving

Recommended Practices:

  1. Never decrease delays below 5 seconds — the defaults are tuned for reliability

  2. Use the bulk_search tool instead of rapid sequential searches — it includes built-in delays

  3. Add extra buffer during bulk operations — consider setting GS_MIN_DELAY=10.0 for large jobs

  4. Use a proxy service (free proxy or ScraperAPI) to distribute requests across multiple IPs

  5. Monitor for 429 errors — if you see them, increase delays immediately and wait before retrying

  6. Spread requests over time — don't run 100 queries in 5 minutes, even with delays

Recovery from IP Blocks

If your IP gets blocked:

  • Wait 24-48 hours for the temporary block to expire

  • Use a proxy — enable GS_PROXY_TYPE=free or scraperapi to route through different IPs

  • Change your network — use a different WiFi/ISP temporarily if possible

  • Contact support — for persistent blocks, escalate to Google Scholar support

Choosing Appropriate Delays

Scenario

GS_MIN_DELAY

GS_MAX_DELAY

Notes

Single searches

5.0

15.0

Default; safe for occasional queries

Bulk operations

10.0

20.0

Use for batch jobs; prevents rapid-fire requests

Heavy load

15.0

30.0

Use with proxy for large-scale research

Aggressive ⚠️

<5.0

<10.0

Not recommended; high risk of IP blocking

Troubleshooting

"Error: 429 Too Many Requests"

You've hit Google Scholar's rate limit. Solutions:

  1. Increase delays: Set higher GS_MIN_DELAY and GS_MAX_DELAY

  2. Use a proxy: Set GS_PROXY_TYPE=free or use ScraperAPI

  3. Wait and retry: Google Scholar may be temporarily blocking; try again later

"No results found"

  • Check your query syntax (Google Scholar supports advanced search operators)

  • Ensure the paper title is spelled correctly

  • Try a simpler query with fewer keywords

[BLOCKED] / "JavaScript bot verification"

Google Scholar sometimes answers automated clients with a JavaScript "Verifying..." page or a sign-in redirect instead of results. The server detects this and pauses Scholar requests for GS_BLOCK_COOLDOWN seconds and returns [BLOCKED] instead. Delays and ordinary proxies do not get past the bot check; a JavaScript-capable proxy (GS_PROXY_TYPE=scraperapi) may.

Using browser cookies (experimental)

Scholar's bot check needs JavaScript, which scholarly does not run. A real browser passes it once and keeps the resulting cookies; handing those cookies (and the same User-Agent) to the server lets scholarly reuse that verified session.

  1. Open a private/incognito window and do not log in to Google.

  2. Go to https://scholar.google.com, run any search, solve the CAPTCHA if one appears, and wait until results show.

  3. Open the developer tools, Network tab, reload, right-click the request named scholar?... and choose Copy > Copy as cURL (or Copy request headers).

  4. Run:

    google-scholar-mcp set-cookies

    It reads the clipboard, saves the cookies and the User-Agent to ~/.config/google-scholar-mcp/cookies (readable only by you) and runs doctor. The server reads that file automatically, so no environment variables are needed: just restart it. Without a clipboard tool, use google-scholar-mcp set-cookies --stdin < copied.txt.

To manage the file yourself instead, put the cookie header value in a file (chmod 600) and set GS_COOKIES_FILE and GS_USER_AGENT.

Notes: use the same machine and network as the server (cookies are usually tied to IP address and User-Agent); they expire, so repeat the steps when doctor reports BLOCKED again; never use cookies from a logged-in Google session (the server warns about login cookies such as SAPISID). Cookie values are never logged or printed; doctor shows only their names.

Author profile pages (/citations) now require a signed-in Google session. This server deliberately does not use login cookies, so it has no author tool.

"Connection timeout"

  • Increase GS_TIMEOUT if your network is slow

  • Check your internet connection

  • Verify proxy settings if using a proxy

Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/your-feature)

  3. Commit your changes with clear messages

  4. Push to your fork

  5. Open a pull request

Tests

poetry run pytest tests/unit                  # fast, offline
poetry run pytest tests -m "not integration"  # what CI runs
poetry run pytest tests -m integration        # live Google Scholar, slow

tests/integration drives the real server through an in-memory MCP client against live Google Scholar and is marked integration automatically. If Scholar blocks your IP, those tests skip instead of failing. They also run weekly via the Integration tests workflow.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

License

See LICENSE file

Available Tools

5 tools
get_bibtexA

Get BibTeX citation entry for a paper.

Identify the paper with scholar_id from an earlier search result when you have one.

Args: title (str | None): Title of the paper to get BibTeX for. scholar_id (str | None): scholar_id of a paper from an earlier search result.

Returns: str: BibTeX entry.

Raises: ScholarBlockedError: If Google Scholar blocks the client. ScholarRateLimitError: If Google Scholar throttles the request after retries. ScholarInvalidArgumentError: If no identifier is given. ScholarNotFoundError: If nothing matches.

Inputs: title, scholar_id. Returns: result

get_citationsA

Get papers that cite a given paper.

With only scholar_id the cited paper's title is not fetched (one request fewer) and is omitted. To page, call again with offset set to the next_offset of the previous response (None: no more), and prefer scholar_id for the following pages.

Args: title (str | None): Title of the paper whose citations to retrieve. max_results (int): Maximum citing papers to return (1-20, default 10). scholar_id (str | None): scholar_id of a paper from an earlier search result. offset (int): Number of citing papers to skip (default 0). Scholar serves at most the first 1000.

Returns: CitationResponse: Citing papers, the cited paper's title and the total citation count when known, and offset / next_offset for paging.

Raises: ScholarBlockedError: If Google Scholar blocks the client. ScholarRateLimitError: If Google Scholar throttles the request after retries. ScholarInvalidArgumentError: If no identifier is given. ScholarNotFoundError: If nothing matches.

Inputs: title, offset, scholar_id, max_results. Returns: Papers that cite a given paper.

get_paper_detailsA

Get full details of a specific paper.

Identify the paper with scholar_id from an earlier search result when you have one; a title search takes the first hit, which can be a different paper.

Args: title (str | None): The exact (or close) title of the paper. scholar_id (str | None): scholar_id of a paper from an earlier search result.

Returns: PaperDetails: Details of the best-matching paper.

Raises: ScholarBlockedError: If Google Scholar blocks the client. ScholarRateLimitError: If Google Scholar throttles the request after retries. ScholarInvalidArgumentError: If no identifier is given. ScholarNotFoundError: If nothing matches.

Inputs: title, scholar_id. Returns: A paper with details, citation history and BibTeX.

search_papersA

Search Google Scholar for academic papers by keyword.

To page, call again with offset set to the next_offset of the previous response (None means there are no more results). Each page costs at least one slow request: only page when the user needs more.

Args: query (str): Search query (same syntax as Google Scholar search box). max_results (int): Maximum number of results to return (1-20, default 10). year_from (int | None): Filter to papers published in or after this year. year_to (int | None): Filter to papers published in or before this year. sort_by (str): Sort order — "relevance" (default) or "date". include_patents (bool): Include patents in results (default True). offset (int): Number of results to skip (default 0). Scholar serves at most the first 1000 results of a query.

Returns: SearchResponse: Matching papers, with offset and next_offset for paging.

Raises: ScholarBlockedError: If Google Scholar blocks the client. ScholarRateLimitError: If Google Scholar throttles the request after retries. ScholarInvalidArgumentError: If offset reaches past the first 1000 results.

Inputs: query (required), offset, sort_by, year_to, +3 more. Returns: Result of a single keyword search.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    Each tool targets a distinct operation: keyword search, single-paper details, citations, batch search, and BibTeX export. The only overlap is bulk_search versus search_papers, but the description explicitly frames bulk_search as a rate-limited multi-query batch whose results must be paged via search_papers, which resolves the boundary. get_paper_details and get_bibtex are close but differentiated by output type.

    Naming Consistency4/5

    Names are uniformly snake_case and verb-first (search_papers, get_paper_details, get_citations, get_bibtex), so an agent can predict behavior from the name. The minor deviation is bulk_search, which uses a modifier rather than a clear object noun in the get_/search_ pattern.

    Tool Count5/5

    Five tools is a tight, well-scoped surface for a Google Scholar search server, with each tool covering a distinct research workflow (discover, inspect, trace citations, export, batch). No tool feels redundant or padded.

    Completeness4/5

    Core lifecycle is covered: search, page, inspect details, follow citing papers, export BibTeX, and batch queries. The notable gap is the reverse citation direction (references/cited-by is one-sided) plus no author-profile or related-articles lookup, which are common scholarly research needs an agent would hit.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A local MCP server that allows users to search Google Scholar for academic papers by topic, author, and year range without requiring API keys. It utilizes web scraping to provide paginated results for research and academic exploration through natural language.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables academic research by searching Google Scholar, fetching paper content, and converting web pages to clean Markdown.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for searching academic papers via Google Scholar, retrieving metadata and abstracts, with support for Chinese queries and auto-translation.
      87
      MIT