Research Buddy Server

A powerful literature review assistant for AI agents, powered by the Semantic Scholar Graph API. Gives your AI agent the ability to search, explore, and cite academic papers through 15 specialized tools.

Features

• Advanced Search: Find papers by keyword with filters for discipline, venue, document type, citation count, date range, and open access availability. Includes pagination.
• Bulk Search: Boolean query syntax (+"LLM" +hallucination -survey) with sorting by citation count or recency, and token-based pagination through up to 10 million results.
• Full-Text Snippet Search: Search inside paper content, not just metadata. Returns ~500-word excerpts with section labels (Introduction, Methods, etc.).
• Title Matching: Resolve plain-text references like "Attention Is All You Need" to a paper ID with a confidence score.
• Smart Recommendations: AI-driven paper discovery using multiple seed papers and negative examples to steer results.
• Rich Paper Details: Full metadata including external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, and more.
• Citation Graph with Context: Explore who cited a paper and what it references, with the actual citation sentence, intent classification (methodology, background, result comparison), and influence scoring.
• Author Discovery: Search for authors by name, view h-index, paper count, citation count, affiliations, and publication list.
• Multi-Format Citations: Generate citations in APA, MLA, Chicago, IEEE, and BibTeX formats.
• Citation Intersection: Find papers that appear in the citation graph of multiple papers, revealing bridging work between research threads.
• PDF Extraction: Extract plain text from Open Access PDFs for immediate reading.
• Batch Processing: Efficiently fetch metadata for multiple papers at once.

Installation

Option A: Install from GitHub (recommended)

pip install git+https://github.com/Usama1002/research-buddy-mcp.git

Option B: Install from source (for development)

git clone https://github.com/Usama1002/research-buddy-mcp.git
cd research-buddy-mcp
pip install -e .

Configuration

Create a .env file or set the environment variable:

SEMANTIC_SCHOLAR_API_KEY=your_api_key_here

The server works without an API key but with lower rate limits. Get a free key at semanticscholar.org/product/api.

Usage

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

Add this to your .claude/settings.json or project's .mcp.json:

{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Antigravity (Gemini)

Add the following to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "args": [],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code

Native (Windows, macOS, Linux)

Create a .vscode/mcp.json in your project root:

{
  "servers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Alternatively, add it globally in your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "research-buddy": {
        "command": "research-buddy-mcp",
        "env": {
          "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

WSL (Windows Subsystem for Linux)

VS Code's extension host runs in the Windows process space and cannot directly resolve WSL binaries. You must explicitly delegate the command to WSL using the full path to the installed binary.

First, find the binary path inside WSL:

which research-buddy-mcp
# Example output: /home/<your-username>/.local/bin/research-buddy-mcp

Then add the following to your VS Code settings.json (or .vscode/mcp.json):

{
  "mcp": {
    "servers": {
      "research-buddy": {
        "command": "wsl",
        "args": [
          "--",
          "/home/<your-username>/.local/bin/research-buddy-mcp"
        ],
        "env": {
          "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Replace /home/<your-username> with your actual WSL username.

Tools

Search & Discovery

Tool	Description
search_papers	Search for papers by keyword with advanced filters: fields of study, publication type, venue, citation count, date range, open access, and pagination.
bulk_search_papers	Boolean query search (+, |, -, "phrases", wildcards) with sorting by citation count or date. Paginate through up to 10M results via continuation tokens.
search_paper_snippets	Full-text search inside papers. Returns ~500-word text excerpts with the section where the match was found (e.g. Introduction, Methods).
match_paper_by_title	Resolve a plain-text title (e.g. "Attention Is All You Need") to a paper ID with a confidence score.
search_authors	Find researchers by name. Returns author profiles with h-index, paper count, citation count, and affiliations.

Paper Details & Metadata

Tool	Description
get_paper_details	Full metadata for a paper: abstract, TLDR, external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, citation/reference counts, and more. Accepts Semantic Scholar IDs, DOIs (DOI:...), and arXiv IDs (ARXIV:...).
batch_get_papers	Retrieve details for multiple papers in a single request.
read_pdf_text	Download and extract plain text from an open-access PDF URL.

Citation Graph

Tool	Description
get_citations	Papers that cited a given work, with citation context (the actual sentence), intent classification (methodology, background, result comparison), influence flag, and pagination. Filter to influential citations only.
get_references	Papers referenced by a given work, with the same context, intent, and influence data.
find_common_citations	Find papers at the intersection of multiple citation graphs. Given 2+ papers, discover which papers cite all of them (or are referenced by all of them).

Recommendations

Tool	Description
get_related_papers	AI-driven recommendations from Semantic Scholar's recommendation engine. Accepts multiple seed papers and optional negative examples to steer results away from unwanted directions.

Authors

Tool	Description
get_author_details	Author profile: name, affiliations, h-index, paper count, citation count, and publication list.

Citations & Export

Tool	Description
get_paper_bibtex	Ready-to-use BibTeX citation string.
get_paper_citation	Formatted citation in APA, MLA, Chicago, IEEE, or BibTeX style.

Example Workflows

Systematic Literature Review

1. bulk_search_papers('"large language model" +hallucination', sort='citationCount:desc')
2. Filter to top-cited results, then get_paper_details for each
3. get_references with influential_only=True to find foundational work
4. get_paper_citation for each in your preferred format

"Find papers like X but not like Y"

1. match_paper_by_title('Attention Is All You Need') -> get paper ID
2. get_related_papers(paper_ids=[attention_id], negative_paper_ids=[bert_id])

Find bridging work between two research areas

1. find_common_citations([paper_A_id, paper_B_id], direction='citations')
   -> papers that cite BOTH A and B
2. find_common_citations([paper_A_id, paper_B_id], direction='references')
   -> papers referenced BY BOTH A and B

Find a specific claim in the literature

1. search_paper_snippets('chain-of-thought prompting improves reasoning on math')
   -> returns exact text excerpts with section labels

Troubleshooting

spawn research-buddy-mcp ENOENT in VS Code

This error means VS Code cannot find the research-buddy-mcp executable. This is common when using WSL on Windows, because VS Code's extension host runs in Windows and does not have access to WSL's PATH.

Fix: Use the WSL-specific configuration above, pointing to the full binary path returned by which research-buddy-mcp inside your WSL terminal.

Rate Limiting

Without an API key, requests share a global rate limit across all unauthenticated users. If you see 429 Too Many Requests errors, get a free API key and set it in your configuration. The server retries rate-limited requests automatically with exponential backoff.

License

MIT