ZidongS/iKnow-MCP-Server-SerpApi-Google-Scholar-

iKnow MCP Server (SerpApi Google Scholar)

An MCP (Multi-agent Control Protocol) server that wraps the SerpApi Google Scholar API, enabling research agents to pull structured scholar SERP data with full control over every official parameter. The layout mirrors Semantic-Scholar-MCP-Server, ensuring consistent tooling and simple deployment.

Highlights

• Complete Parameter Coverage – Exposes every documented option (q, cites, cluster, as_ylo/as_yhi, scisbd, hl, lr, start, num, as_sdt, safe, filter, as_vis, as_rr, no_cache, async, zero_trace, output, json_restrictor, etc.).
• Robust Validation – Enforces mutually exclusive combinations (e.g., cluster vs. q/cites, no_cache vs. async) and guards against invalid data types or ranges.
• Agent-friendly Tools – Provides three MCP tools (google_scholar_search, google_scholar_cited_by, google_scholar_versions) covering exploration, citation tracing, and version discovery.
• Flexible Configuration – Accepts SerpApi credentials via environment variable or config.yaml.

Installation

Prerequisites

• Python 3.12+
• pip

Install dependencies

cd /mnt/sdb2/szd/Agent/iknow-mcp-server
pip install -e .

This installs:

• mcp – MCP server runtime
• requests>=2.31 – HTTP client
• pyyaml>=6.0 – Config parsing

Configure the API Key

The SerpApi Google Scholar endpoint requires an API key. Choose one of the following:

1. Environment Variable (recommended)

   export SERPAPI_API_KEY=your_private_key
   

2. Configuration File

   serpapi:
     api_key: your_private_key
   

Environment variables override file settings.

Run the Server

python server.py

By default the MCP server binds to 127.0.0.1:6667 and uses sse transport.

Available Tools

google_scholar_search

Full-featured SERP access. Example:

google_scholar_search(
    query="graph neural network",
    as_ylo=2022,
    as_yhi=2024,
    hl="en",
    num=10,
    filter=1,
    as_vis=0
)

google_scholar_cited_by

Forward citation exploration with optional filtering:

google_scholar_cited_by(
    cites="1275980731835430123",
    query="applications",
    as_ylo=2019
)

google_scholar_versions

Enumerate every Scholar version (publisher copy, arXiv, repositories):

google_scholar_versions(
    cluster="1275980731835430123",
    num=5,
    hl="en"
)

All tools return SerpApi’s JSON payload verbatim, so agents can parse organic_results, metadata, pagination, and auxiliary sections without loss.

Error Handling

• Missing API key → RuntimeError
• Invalid or conflicting parameters → ValueError
• Upstream non-2xx responses → RuntimeError including HTTP status and payload

Development Notes

To add new tools, replicate the pattern in server.py: create a @mcp.tool, validate arguments, call _perform_search, and return JSON. Extending to other SerpApi engines only requires new helper functions and constants.