Provenance-first scholarly research infrastructure for Model Context Protocol clients.
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
OpenPapers uses each provider for a defined part of the research workflow:
| Source | Role | Authentication |
|---|---|---|
| arXiv | Preprint search and metadata | Not required |
| Crossref | DOI and bibliographic metadata | Not required |
| OpenAlex | Open scholarly metadata and citation relationships | Not required |
| Semantic Scholar | Paper metadata, authors, references, citations, and recommendations | Optional API key |
| GitHub | Repository discovery, revisions, contents, and implementation evidence | Optional token; anonymous access is rate-limited |
| Hugging Face | 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/arrogance231/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 36 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 - 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 APIs
Read 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:
- Documentation index
- Installation
- Configuration reference
- Usage and MCP tools
- Architecture
- Provider integrations
- Provenance and reproducibility
- Known limitations
- Roadmap
- Release and deployment
Version 0.1.0 is the current package baseline. The project prioritizes provenance and citation verification before automatic citation output.
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.