paperSearch
Provides tools for biomedical entity normalization, relation mining, and article search using PubTator3, which annotates PubMed articles with entities, relations, and evidence.
Provides tools to search academic papers, retrieve paper metadata, traverse citation graphs, and get paper recommendations using the Semantic Scholar API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@paperSearch Find recent papers on immunotherapy for cancer."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SearchPaper
SearchPaper is a literature-first infrastructure layer for agent-assisted research. It searches open scholarly literature, normalizes identifiers, merges duplicate records conservatively, preserves provenance, and exports traceable results for downstream agents or human review.
SearchPaper is not a full research agent, systematic-review engine, evidence evaluator, PDF parser, or Zotero replacement. It provides structured literature records and provenance; interpretation stays with the user or a downstream research workflow.
🔎 At a Glance
Area | What SearchPaper provides |
📚 Sources | PubMed, Crossref, OpenAlex, Europe PMC, arXiv, bioRxiv, medRxiv, Semantic Scholar, Unpaywall, OpenCitations, PubTator3 |
🧬 Biomedical workflows | MeSH lookup, PubMed related articles, DOI/PMID/PMCID conversion, PubTator3 literature signals |
🔗 Identifiers | DOI, PMID, PMCID, arXiv, OpenAlex, Semantic Scholar IDs |
🧾 Provenance | Source records, merge reasons, conflicts, warnings, trace fields |
🧠 Agent access | CLI plus MCP tools for OpenCode, Codex, Claude, and other MCP clients |
📦 Exports | JSON, JSONL, BibTeX, RIS, NBIB, ENW, Markdown, Zotero CSV, Obsidian notes, APA, MLA |
🔓 API keys | Core workflows are no-key usable; optional keys improve rate limits and coverage |
Related MCP server: mcp-semanticscholar
✨ What It Does
Multi-source literature search across open scholarly APIs.
Identifier resolution for common scholarly IDs.
Conservative duplicate merge with provenance and conflict preservation.
Local SQLite cache for speed and reproducibility.
Full-text readiness via OA links, Europe PMC XML anchors, and full-text availability fields.
Structured literature signals from PubTator3 with explicit interpretation warnings.
CLI-first workflows plus a small, stable MCP tool surface.
Agent integration helpers for OpenCode, Codex, and Claude.
⚡ Quick Start
git clone <repo-url> ~/Publish/PaperSearch
cd ~/Publish/PaperSearch
uv sync --extra dev
uv run pytest -qTask | Command |
Search literature |
|
Resolve a DOI |
|
Check source health |
|
Run diagnostics |
|
Start MCP server |
|
For an editable local install:
uv pip install -e .After installation, the package provides the searchpaper CLI.
⚙️ Configuration
SearchPaper reads ~/.config/searchpaper/config.json. Environment variables
override file values.
{
"semantic_scholar_api_key": "YOUR_KEY",
"crossref_email": "you@example.com",
"openalex_email": "you@example.com",
"ncbi_api_key": "YOUR_NCBI_KEY",
"cache_path": "~/.cache/searchpaper/cache.db"
}Variable | Maps to | Description |
|
| SQLite cache file |
|
| Config file path |
|
| Optional Semantic Scholar key |
|
| Crossref polite-pool email |
|
| OpenAlex polite-pool email |
|
| Optional NCBI key |
🧭 Core CLI Workflows
Workflow | Command |
Plan source routing |
|
Search literature |
|
Get work by PMID |
|
Resolve identifier |
|
Expand from a seed work |
|
Build context pack |
|
Fetch full-text anchors |
|
Probe sources |
|
Explain source behavior |
|
Diagnose source health |
|
Save project trace |
|
Export saved trace |
|
Lookup MeSH |
|
Find related PubMed articles |
|
Convert PubMed IDs |
|
Batch process inputs |
|
Verify references |
|
Export results |
|
Inspect capabilities |
|
🧩 MCP and Agent Integration
Start the default stdio MCP server:
searchpaper serve --mcpStart a remote HTTP/SSE MCP server with searchpaper[remote] installed:
searchpaper serve --mcp --transport http --host 127.0.0.1 --port 8000 --path /mcpTool | Purpose |
| Multi-source literature search |
| Source-routing plan without a live search |
| Fetch one work by identifier |
| Resolve and merge multiple identifiers |
| Source health and optional catalog |
| PubMed MeSH descriptor lookup |
| PubMed related article IDs |
| DOI/PMID/PMCID conversion |
| Biomedical entity/relation signals |
| Citations, references, and related papers |
| Export structured records |
Agent | Install command | Output |
OpenCode |
| MCP config plus |
Codex |
| MCP snippet plus SearchPaper instructions |
Claude |
| MCP snippet plus SearchPaper instructions |
All |
| Scaffolds all supported integrations |
Review generated files and enable the searchpaper MCP server in your agent
settings.
📖 Full-Text Readiness
SearchPaper reports full-text availability without requiring PDF parsing.
Records may include full_text_availability, open_access_pdf, and canonical
URLs such as doi, pubmed, pmc, oa_url, and oa_pdf_url.
searchpaper resolve --doi 10.1038/s41586-021-03819-2 --json
searchpaper get --pmcid PMC8371605 --sources europepmc --anchors --json
searchpaper context --doi 10.1038/s41586-021-03819-2 --json
searchpaper get --doi 10.1038/s41586-021-03819-2 --download-pdf paper.pdf --json
searchpaper get --pmcid PMC8371605 --download-xml paper.xml --jsonPDF parsing remains optional and out of scope.
🛡️ Failure Modes and Signal Rules
Topic | Behavior |
Source degradation | Public APIs can fail; optional sources warn and continue |
Required sources |
|
Preferred sources |
|
Biomedical signals | PubTator3/co-mention signals are not proof of causality |
Evidence evaluation | Out of scope; SearchPaper returns records, provenance, and signals |
🗂️ Cache, Privacy, and Project Mode
Default cache:
~/.cache/searchpaper/cache.dbBypass cache:
searchpaper search "query" --no-cache --jsonProject mode:
searchpaper init
searchpaper search "HCC TACE PD-1" --json --save
searchpaper project traces
searchpaper project export <trace_id> --format bibtexThe cache may contain raw API responses and query identifiers. Store it accordingly.
🧪 Development
uv sync --extra dev
uv run pytest -q
uv run ruff check .
uv run ruff format .CI should rely on fixture-backed tests. Live public APIs are useful for manual checks but should not be required for routine validation.
📜 License
MIT
Available Tools
11 toolsconvert_identifiersC
Convert DOI/PMID/PMCID identifiers through the NCBI ID converter.
Inputs: identifiers (required). Returns: object
expand_from_workC
Expand from a known work by citations, references, or similar papers.
Inputs: identifier (required), by, limit, sources, +1 more. Returns: object
export_recordsC
Export a list of works to a supported format.
Inputs: works (required), format. Returns: object
get_source_statusB
Return the health status of all configured sources.
Inputs: include_catalog. Returns: object
get_workB
Get a work by identifier (DOI, PMID, PMCID, arXiv, etc.).
Inputs: identifier (required), sources, source_modes, identifier_type. Returns: object
lookup_meshC
Lookup MeSH descriptors for a biomedical term.
Inputs: term (required), limit. Returns: object
plan_literature_searchC
Plan source routing and ranking without running a live search.
Inputs: query (required), sort, profile. Returns: object
resolve_identifiersC
Resolve a list of identifiers across sources and return merged records.
Inputs: identifiers (required), sources, source_modes. Returns: object
search_literatureC
Search open scholarly literature across configured sources.
Inputs: query (required), sort, year, limit, +7 more. Returns: object
search_literature_signalsC
Search biomedical literature signals via PubTator3.
Inputs: limit, query, entity1, entity2, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Several tools have overlapping purposes: search_literature vs. search_literature_signals both search, resolve_identifiers vs. convert_identifiers both handle IDs, and find_related_articles vs. expand_from_work both find related works. Descriptions clarify differences, but confusion is possible.
Most tools follow a consistent verb_noun pattern (search_literature, get_work, resolve_identifiers, export_records). Minor deviations like expand_from_work (verb-preposition) and lookup_mesh (terse) exist but do not disrupt overall predictability.
With 11 tools, the set is well-scoped for a literature search server. Each tool serves a distinct step in discovery, retrieval, and export without unnecessary redundancy or bloat.
The tool set covers the core scholarly search workflow: planning, searching, retrieving by ID, converting identifiers, expanding from known works, and exporting. Minor gaps exist, such as full-text retrieval or advanced citation analysis, but they are not critical for the stated purpose.
Maintenance
Related MCP Connectors
Search biomedical papers, inspect publication records, and traverse citation or semantic graphs.
Search PubMed/Europe PMC, fetch articles and full text (PMC/EPMC/Unpaywall), citations, MeSH terms.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Research papers for AI agents: PubMed, arXiv, Crossref; citations, references, open access texts
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides structured PubMed literature data for LLM agents, supporting search, caching, and open-access full-text downloads via the MCP protocol.536 npm11Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query the Semantic Scholar Academic Graph for scholarly paper data, supporting tools for search, retrieval, and analysis.73 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables PubMed literature search, metadata retrieval, BibTeX export, and evidence table generation for biomedical research agents.2MIT
- AlicenseAqualityCmaintenanceEnables LLM agents to search biomedical literature, retrieve article details, find related papers, manage caching, and download open-access full texts through MCP with structured, agent-friendly responses.5Apache 2.0