mcp-scholarly

You can automatically install mcp-scholarly for Claude Desktop using the Smithery CLI:

npx -y @smithery/cli install mcp-scholarly --client claude

The zorp agent requires a search-capable MCP tool to run the validate command. mcp-scholarly satisfies this requirement because its tools (search-arxiv, search-google-scholar) contain the search verb.

CLI Usage

zorp-agent --yes \
  --mcp "stdio:scholarly:uv:run:mcp-scholarly" \
  validate "<your research question>"

Persistent Configuration

To configure it once in .zorp/mcp.toml:

[[server]]
name = "scholarly"
transport = "stdio"
command = "uv"
args = ["run", "mcp-scholarly"]
trust = "sandbox"
timeout_secs = 60

Note on Timeouts: While search-arxiv is fast (~1s), search-google-scholar uses a proxy pool and can be unpredictable. Setting timeout_secs = 60 provides necessary headroom.

To use mcp-scholarly with Claude Desktop, you must add it to your claude_desktop_config.json file.

Config Locations:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Choose the configuration block that matches your installation method (Published via uvx, Development via uv, or Docker).

// Published Servers Configuration
"mcpServers": {
  "mcp-scholarly": {
    "command": "uvx",
    "args": [
      "mcp-scholarly"
    ]
  }
}

If you prefer running the server via Docker, add the following to your Claude Desktop configuration:

"mcpServers": {
  "mcp-scholarly": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "mcp/scholarly"
    ]
  }
}

The mcp-scholarly server includes an optional SerpBase provider to bypass Google Scholar rate-limiting on datacenter IPs. This provider is only registered and available if the SERPBASE_API_KEY environment variable is set. If the key is missing, the server will start normally but the SerpBase search tool will not be available.

export SERPBASE_API_KEY='your_api_key_here'

Because MCP servers communicate over stdio, it is recommended to use the MCP Inspector for debugging. You can launch it using npx and uv:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-scholarly run mcp-scholarly

Once launched, the Inspector will provide a URL that you can open in your browser to interact with the server.

npx @modelcontextprotocol/inspector uv --directory /Users/adityakarnam/PycharmProjects/mcp-scholarly/mcp-scholarly run mcp-scholarly

The search-arxiv tool allows you to search arXiv for academic articles related to a specific keyword. It does not require an API key.

Arguments:

• keyword (string, required): The search term for the article.

search-arxiv: Search arxiv for articles related to the given keyword.
  Takes "keyword" as required string arguments

The search-google-web tool performs a Google web search via the SerpBase API.

Requirement: This tool is only registered and available if the SERPBASE_API_KEY environment variable is set.

The search method in ArxivSearch implements exponential backoff retries when the arXiv API fails. You can control the maximum number of retry attempts by setting the SCHOLAR_MAX_RETRIES environment variable.

• Environment Variable: SCHOLAR_MAX_RETRIES (integer)
• Default Value: 3 if the variable is unset, empty, or invalid.
• Behavior: If a retry occurs, the delay follows an exponential backoff pattern starting at 1 second, capped at 10 seconds.

# Example: Setting the retry limit via environment variable
export SCHOLAR_MAX_RETRIES=5

You can control the number of retry attempts for Google Scholar searches using the SCHOLAR_MAX_RETRIES environment variable. This is useful for managing how the server handles fetch failures or CAPTCHA blocks.

• Default value: 3 if the environment variable is not set or is invalid.
• Behavior: The server uses an exponential backoff strategy for retries. The initial delay is 1s, doubling with each attempt, up to a maximum of 10s per delay.
• Note: Retries are kept relatively low because MCP clients often enforce their own request timeouts. Excessive retrying may result in MCP error -32001: fetch failed if the total time exceeds the client's timeout.

The SerpBaseSearch class provides a way to perform Google web searches via the SerpBase REST API. It returns a list of formatted strings containing the Title, Summary, and URL for up to 10 organic search results.

Requirements:

• SERPBASE_API_KEY must be set in the environment.
• The search method handles the API request and automatically closes the underlying HTTP client.

from mcp_scholarly.serpbase_search import SerpBaseSearch

searcher = SerpBaseSearch()
if searcher.available:
    results = searcher.search("machine learning research")
    for result in results:
        print(result)
    searcher.close()