OpenPapers is an MCP server for provenance-first scholarly research: it searches, retrieves, parses, extracts, compares, verifies, and organizes research papers and related code/models while preserving source identity and uncertainty.
Search scholarly metadata across arXiv and Crossref with transparent ranking.
Retrieve canonical papers by ID, DOI, or arXiv ID and get BibTeX without fabricating metadata.
Explore the research graph: references, citations, related papers, and author profiles.
Read and parse bounded HTML papers, then search within the parsed content.
Extract source-located facts, claims, and explicitly reported training parameters from papers.
Compare papers, methods, or paper recipes against revision-pinned repository configuration without executing code.
Verify persisted claims and report evidence status without upgrading derived evidence.
Find GitHub implementations, Hugging Face models, datasets, and repository configuration files.
Build cited literature reviews, implementation reports, or reproducibility reports with facts and recommendations separated.
Manage persistent collections: create, add/remove papers, refresh, delete, and export/import portable ResearchPacks.
Run vector search over indexed paper content when a vector backend is configured.
Searches arXiv for preprints and retrieves their metadata, supporting scholarly paper discovery and access to preprint records.
Enables repository discovery, revision-pinned file inspection, and implementation evidence gathering without executing repository code, supporting reproducibility comparisons.
Supports model and dataset discovery, including model and dataset cards, revisions, and linked papers.
Provides paper metadata, authors, references, citations, and recommendations through 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., "@OpenPapers Search arXiv for recent papers on MCP servers and summarize their key claims with sources."
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.
OpenPapers is a Model Context Protocol (MCP) server for scholarly retrieval, paper ingestion, and reproducible research workflows. It preserves source identities, evidence, uncertainty, and provider failures instead of presenting generated output as verified research.
OpenPapers combines scholarly and developer sources through replaceable provider adapters. It treats downloaded papers and repository content as untrusted data and never executes them.
Searches arXiv, Crossref, OpenAlex, and Semantic Scholar
Preserves DOI, arXiv, OpenAlex, and Semantic Scholar identities during reconciliation
Discovers citations, references, related papers, authors, repositories, models, and datasets
Acquires bounded HTML and PDF content, with GROBID parsing and optional local fallbacks
Extracts source-located facts, claims, conflicts, training parameters, and reproducibility reports
Inspects revision-pinned GitHub configuration files without executing repository code
Stores research in SQLite with full-text search (FTS5) or PostgreSQL with pgvector
Manages collections, portable ResearchPacks, refresh operations, and vector retrieval
Serves MCP over stdio or stateless Streamable HTTP
Related MCP server: academic-research-plugin
OpenPapers serves as the first-level research server for OpenGrad, a provenance-first empirical study of tool-use post-training in small open-weight language models.
OpenGrad deliberately does not pre-download a fixed paper corpus: which papers matter only becomes clear once dataset materialization, training, and evaluation are underway. Instead of speculative bulk acquisition, OpenGrad queries OpenPapers on demand for search, bounded retrieval, and fact or training-parameter extraction, then records each result's source identity, revision, and locator in its verified bibliography before the evidence is used.
This keeps the OpenGrad repository small, avoids downloading papers that may never be needed, and still satisfies OpenGrad's provenance rules: every claim traces to a primary source with an explicit locator and uncertainty status. OpenGrad remains fully reproducible without OpenPapers; see OpenGrad's boundary documentation.
OpenPapers uses each provider for a defined part of the research workflow:
Source | Role | Authentication |
Preprint search and metadata | Not required | |
DOI and bibliographic metadata | Not required | |
Open scholarly metadata and citation relationships | Optional email for polite API access | |
Paper metadata, authors, references, citations, and recommendations | Optional API key | |
Repository discovery, revisions, contents, and implementation evidence | Optional token; anonymous access is rate-limited | |
Model and dataset discovery, cards, revisions, and paper links | Optional token |
Provider selection depends on the identifier, query, and available metadata. No provider is authoritative for every field.
Choose a local Node.js installation or the complete Docker Compose stack:
Local runtime: Node.js 22.5 or newer and npm
Container runtime: Docker Engine with Compose support
Optional PDF parsing: GROBID, PyMuPDF, or Docling
Optional persistent vector search: PostgreSQL with pgvector
The container image uses Node.js 24. Docker Compose supplies PostgreSQL, pgvector, and GROBID.
Install the locked dependencies and compile the TypeScript source:
git clone https://github.com/arjhinety/OpenPapers.git
cd openpapers
npm ci
npm run buildCopy .env.example to .env if you want persistent SQLite storage or optional provider credentials:
cp .env.example .envThe example configuration stores SQLite data at ./data/research.sqlite. OpenPapers otherwise uses an in-memory SQLite database when RESEARCH_DB_PATH is unset.
Use stdio for a local MCP client. The following .vscode/mcp.json example assumes the repository is your open VS Code workspace:
{
"servers": {
"openpapers": {
"type": "stdio",
"command": "node",
"args": ["./dist/mcp/server.js"]
}
}
}Other MCP clients use the same command and script path, but their configuration keys may differ. Build the project before the client starts the server.
You can also run the stdio server directly for transport diagnostics:
npm startSet MCP_TRANSPORT=http in .env, then start the server:
npm startThe default endpoint is http://127.0.0.1:8787/mcp. Keep it on loopback unless a trusted reverse proxy supplies authentication and Transport Layer Security (TLS).
To run the complete container stack instead, use:
docker compose up --build --waitDocker Compose starts OpenPapers at http://127.0.0.1:8787/mcp, PostgreSQL with pgvector, and GROBID. Stop the stack with docker compose down; the named volumes remain available.
See the installation guide for deployment choices and the configuration reference for every environment variable.
OpenPapers registers 37 bounded tools. The inventory below matches the current server registration:
Retrieval: search_papers, get_paper, get_bibtex, research_method, research_topic
Graphs: get_references, get_citations, get_related_papers, resolve_author
Documents and extraction: read_paper, search_within_paper, extract_paper_facts, extract_paper_claims, extract_training_parameters
Verification and reproducibility: extract_training_recipe, extract_training_recipe_from_url, build_research_report, compare_paper_to_code, compare_papers, compare_methods, verify_claim, reconstruct_research
Developer ecosystem: find_implementations, find_models, find_datasets, find_repository_configs, get_repository_config
Research library: create_collection, list_collections, add_paper_to_collection, remove_paper_from_collection, delete_collection, export_research_pack, import_research_pack, refresh_collection, refresh_paper, vector_search
Tool inputs use bounded Zod schemas. Responses include readable MCP content and structured data where the contract supports it. Follow the usage guide for a representative research workflow.
Requests pass from an MCP transport through tool modules and the research service. Provider adapters handle external APIs, while storage and retrieval components preserve local results.
MCP transport -> tool modules -> ResearchService -> provider adapters
| |
v v
storage/retrieval external APIsRead the architecture, provider, and extension guides for implementation details.
Material claims include evidence records when source data is available. Records can contain source IDs, authors, titles, persistent identifiers, quality labels, evidence types, and locators.
OpenPapers keeps provider failures, conflicts, unavailable values, and heuristic derivations explicit. Generated summaries are not academic sources. Verify them against the cited records.
The project does not execute downloaded documents or discovered repositories. Read the security policy, reproducibility guide, and known limitations before exposing the HTTP transport or relying on extracted results.
Run the complete credential-free validation suite with one command:
npm run checkThe command runs the TypeScript check, architecture rules, production build, and Vitest suite. You can also run each stage separately:
npm run lint
npm run architecture-check
npm run build
npm testLive provider, Docker, GROBID, and model workflow checks remain separate from credential-free tests. Contributors should read CONTRIBUTING.md and the release checklist.
The documentation index groups guides by task and audience:
Version 1.0.0 is the current release baseline. The 1.0 contract: OpenPapers is a provenance-first infrastructure layer for discovering works by identifier or exact title, retrieving, extracting, reconciling, and locating evidence from scholarly sources — with explicit refusal instead of fabrication. High-quality open-ended fuzzy scholarly search is explicitly out of the 1.0 contract (measured at ≈0.5 Recall@10); see known limitations. The project prioritizes provenance and citation verification before automatic citation output.
Quality is gated by a five-level test program (static, offline integration, spawned-process end-to-end, live-provider evaluation, container runtime) with a claims matrix mapping every public claim to recorded evidence; see the test plan. Live-provider metrics are environment-dependent: recorded runs include HTTP 429 rate limits, so exact-title retrieval and identity results are evidence from specific runs, not guarantees. See known limitations before relying on fuzzy discovery or live-provider availability.
The changelog records completed work. The roadmap describes citation metadata, source-aware citation output, and deferred retrieval improvements.
OpenPapers is licensed under the Apache License, Version 2.0. This license covers the project's source code only.
Papers, abstracts, metadata, API responses, datasets, model weights, model cards, and GitHub repositories retain their own licenses and service terms. ACKNOWLEDGEMENTS.md lists the external projects and services used by OpenPapers.
OpenPapers does not maintain an automatic CITATIONS.md file. A formal citation record will be added after the project has a stable public authorship and release identity.
Do not cite generated research responses as original sources. Cite the papers, datasets, and provider records referenced by each response.
Add an existing verified paper to a persistent local collection.
Inputs: paper_id (required), collection_id (required).
Build a cited literature, implementation, or reproducibility report with facts and recommendations separated.
Inputs: query (required), mode, limit.
Compare two bounded method searches and report verified paper overlap without inferring benchmark equivalence.
Inputs: left_method (required), right_method (required), limit.
Compare verified local paper metadata; benchmark comparability stays explicit when evidence is absent.
Inputs: left_paper_id (required), right_paper_id (required).
Compare an explicit paper recipe with extracted revision-pinned repository configuration; repository content is never executed.
Inputs: fields (required), recipe (required), source_url (required), commit_sha.
Create or retrieve a persistent local paper collection.
Inputs: name (required).
Delete a persistent local collection and its memberships without deleting papers.
Inputs: collection_id (required).
Export a deterministic local collection ResearchPack without remote calls.
Inputs: collection_id (required).
Persist compatibility heuristic claims, expose canonical v5 facts, and report explicit conflicts with prior claims.
Inputs: url (required).
Extract compatibility heuristic facts plus canonical v5 facts with source locators; no unsupported values are inferred.
Inputs: url (required).
Extract only explicitly labeled training values with source locators.
Inputs: url (required).
Return only source-backed training parameters. Missing values are never guessed.
Inputs: paper_id (required).
Populate only explicitly reported training recipe fields from a paper URL.
Inputs: url (required).
Find dataset repositories on Hugging Face, including revision, card metadata, and reconciled paper links when available.
Inputs: query (required), limit.
Find GitHub repositories related to a verified paper or method. Status is UNKNOWN unless separately verified.
Inputs: limit, method, paper_id.
Find model repositories on Hugging Face, including revision and card metadata when available.
Inputs: query (required), limit.
List common configuration files at a repository revision without executing or recursively crawling repository content.
Inputs: repo (required), owner (required), ref.
Return canonical BibTeX without fabricating absent metadata.
Inputs: paper_id (required).
Retrieve Semantic Scholar citing works with provenance.
Inputs: paper_id (required), limit.
Retrieve a canonical research work by paper ID, DOI, or arXiv ID.
Inputs: paper_id (required).
Retrieve Semantic Scholar references with provenance.
Inputs: paper_id (required), limit.
Read a repository file statically at an optional revision. Repository content is never executed.
Inputs: path (required), repo (required), owner (required), ref.
Import a bounded JSON ResearchPack as untrusted static metadata; no code is executed.
Inputs: pack_json (required).
List persistent local paper collections and their memberships.
Inputs: no named parameters.
Acquire and parse a bounded HTML paper document with section and reference boundaries.
Inputs: url (required).
Extract a bounded query-independent fact set from an acquired paper and optional exact pinned repository revision, then select facts using a separate query intent. Missing or unavailable evidence remains UNKNOWN; repository content is never executed.
Inputs: fields (required), question (required), paper_url (required), repository_name, +2 more.
Refresh locally stored metadata for every paper in a collection, preserving per-paper outcomes.
Inputs: collection_id (required).
Refresh locally stored metadata through an available provider-native identifier.
Inputs: paper_id (required).
Remove a paper from a persistent local collection without deleting the paper.
Inputs: paper_id (required), collection_id (required).
Search verified literature for a named method with provider transparency and evidence.
Inputs: method (required), limit.
Build a provenance-preserving literature overview. Synthesis is labeled; no unsupported claims are emitted.
Inputs: topic (required), depth, limit, objective.
Resolve a Semantic Scholar author profile and linked paper identifiers.
Inputs: author_id (required).
Search verified scholarly metadata across arXiv and Crossref. Results include provenance and transparent ranking.
Inputs: query (required), limit, topic, venue, +3 more.
Search parsed paper chunks and return source-located matches.
Inputs: url (required), query (required), limit.
Search indexed paper vectors through the configured vector backend.
Inputs: query (required), limit.
Inspect a persisted claim for recorded conflicts; this is not independent scholarly verification and never upgrades derived evidence.
Inputs: claim_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Several tools have overlapping purposes, such as extract_paper_facts vs extract_paper_claims vs verify_claim, and extract_training_parameters vs extract_training_recipe vs extract_training_recipe_from_url. The compare_* family and research_method/research_topic/build_research_report also blur boundaries, though descriptions provide some differentiation.
Most tools follow a clear snake_case verb_noun pattern (create_collection, list_collections, add_paper_to_collection, etc.). However, vector_search is noun-first rather than verb-first, and research_method/research_topic read as noun phrases rather than clear verb actions, creating minor inconsistency.
With 37 tools, the surface area is well beyond the typical 3–15 scope and feels heavy for a single MCP server. While each tool has a narrow role, the large count risks cognitive overload and suggests excessive granularity.
The tool set covers a wide range of research-paper workflows: retrieval, extraction, citation management, comparison, collections, repository/model/dataset lookup, and research-pack import/export. Minor gaps exist around paper updating/deletion and more explicit claim-verification workflows, but the core domain is well represented.
Machine-readable entity discovery with provenance, trust and verified source evidence.
Search and cite research claims with their evidence and reliability scores; publish claimsets.
Multi-engine scholarly research server for search, traversal, full text, and reading lists.
Read-only MCP over an agentic SLR workspace with per-claim citation verification