{ "markdown": "\n\n

\n \n \n \n \"Scholar\n \n

\n\n

\n \"Install\n \"Add\n \"Add\n \"MCP\n

\n\n

Go deeper.

\n\n

\n Find the paper. Follow the evidence. Build the field.\n

\n\n

\n \"PyPI\"\n \"Python\n \"Apache\n \"MCP\n

\n\nScholar MCP turns a research question into a connected body of evidence. It recovers papers from vague descriptions, reaches the work one hop beyond search, opens the primary text, maps the lineage, and carries the selected field into a library that grows with every session.\n\n`Natural-language discovery` · `Related-work discovery` · `Primary evidence` · `Field maps` · `Zotero · Obsidian · Notion connectors`\n\n## Quick demo\n\n![Scholar MCP quick demo](docs/assets/quick-demo.gif)\n\nOne continuous agent flow: `search_papers` → `build_paper_graph` → `paper_info` + `read_paper` → `paper_library` → library connectors.\n\n## How it works\n\n\n \n \n \"Scholar\n\n\n\n \n \n \"Scholar\n\n\nAgents call typed MCP tools over stdio or Streamable HTTP. Scholar returns concise text and structured data, while a persistent SQLite library drives FTS5 search, PDF attachments, JSONL snapshots, and Obsidian, Zotero, and Notion connectors.\n\n## Quick start\n\nClaude Code:\n\n```bash\nclaude mcp add scholar -- uvx scholar-mcp\n```\n\nClaude Desktop or any stdio MCP client:\n\n```json\n{\n \"mcpServers\": {\n \"scholar\": {\n \"command\": \"uvx\",\n \"args\": [\"scholar-mcp\"]\n }\n }\n}\n```\n\nThe direct server exposes the compact core profile. Python 3.10+ and [uv](https://docs.astral.sh/uv/) are required. Optional source keys unlock deeper coverage and higher throughput.\n\nThe repository also ships a research plugin with citation graphs, a local paper library, and the Deep Research skill:\n\n```bash\n# Codex\ncodex plugin marketplace add Liyux3/scholar-mcp\ncodex plugin add scholar-mcp@scholar-mcp\n\n# Claude Code\nclaude plugin marketplace add Liyux3/scholar-mcp\nclaude plugin install scholar-mcp@scholar-mcp\n```\n\nThe same plugin directory follows the Agent Plugins standard for Cursor, Pi, and compatible harnesses. OpenCode can launch `uvx scholar-mcp` as a local MCP; Pi can use `pi-mcp-adapter`.\n\nRelease artifacts also include the PyPI package, multi-architecture GHCR image, and macOS MCPB bundles. See the complete [distribution matrix](docs/DISTRIBUTION.md).\n\n## Tools\n\n| Profile | Tool | Responsibility |\n|---|---|---|\n| Core | `search_papers` | Multi-source retrieval, filters, reranking, and citation discovery |\n| Core | `paper_info` | Paper detail, citations, and references through one selective call |\n| Core | `recommend_papers` | Related work through semantic and citation connections |\n| Core | `search_authors` | Author profiles, affiliations, paper counts, and h-index |\n| Core | `read_paper` | Temporarily fetch and read a complete paper in one call |\n| Core | `download_paper` | Persist a PDF and index it in a collection |\n| Research | `build_paper_graph` | Bounded citation graph with PageRank, bridges, nodes, edges, and Mermaid |\n| Research | `paper_library` | Collections, FTS search, notes, tags, PDFs, and Markdown vault export |\n\n`scholar://status` reports source availability and the actual reranker used without occupying the tool surface. Tool responses retain concise YAML text and also expose structured MCP data.\n\nThe bundled Deep Research skill turns search, paper inspection, graph traversal, and selected library writes into a living field map.\n\n## Retrieval\n\n| Channel | Sources | Query form and role |\n|---|---|---|\n| Semantic | OpenAlex semantic, arxiv.gg, optional Exa | Full natural-language question |\n| Full text | Semantic Scholar snippet search | Matching passages from open-access papers |\n| Broad metadata | OpenAlex, Semantic Scholar, Crossref, optional Scopus | Identity, coverage, citations, and filters |\n| Preprints and conferences | arXiv, OpenReview | Recent work and conference records |\n| Biomedical | PubMed, Europe PMC | Medicine, biology, and full-text repositories |\n| Domain and repository | DBLP, INSPIRE-HEP, DOAJ, CORE, OpenAIRE, HAL | CS, physics, open journals, and repositories |\n| Web fallback | Google Scholar | Best effort; blocking is reported as degradation |\n\nKeyword APIs receive measured source-specific query budgets. Semantic endpoints keep the original question. Every source contributes independently to one canonical evidence pool.\n\nResults are canonicalized across DOI, arXiv, Semantic Scholar, OpenAlex, PubMed, and OpenReview identities. Duplicate records contribute complementary metadata and independent source evidence instead of appearing several times.\n\nDashScope `qwen3-rerank` is the primary reranker when configured; FlashRank is the local fallback. The normal response shows only source coverage, the actual reranker, and actionable degradation. `debug=true` adds per-source yield, latency, provenance, and internal ranking diagnostics.\n\n## Measured retrieval quality\n\n![LitSearch quality comparison](docs/assets/litsearch-quality.svg)\n\nScholar leads the Exa research-paper baseline by **10 points at R@5** and **6 points at R@20** on matched LitSearch.\n\n| System | R@5 | R@10 | R@20 | MRR |\n|---|---:|---:|---:|---:|\n| **Scholar** | **0.62** | **0.68** | **0.70** | **0.442** |\n| Exa `research paper` | 0.52 | 0.58 | 0.64 | 0.435 |\n| BM25 `title + abstract` | 0.46 | 0.46 | 0.56 | 0.335 |\n\nScholar recovered nine R@5 hits that Exa missed; Exa recovered four that Scholar missed.\n\n
\nBenchmark protocol\n\nThe comparison uses the same first 50 LitSearch inline-ACL queries, ground-truth titles, title matcher, and top-20 cutoff. Exa ran with category `research paper`. Scholar used its standard retrieval pipeline with Qwen reranking. BM25 follows the official LitSearch title+abstract implementation: lowercase tokenization, English stopword removal, Porter stemming, and `BM25Okapi` over the 64K-paper corpus. The Scholar/Exa run was collected on 12 May 2026; BM25 was reproduced on 25 August 2026. The frozen summary is in [`docs/benchmarks/litsearch-inline-acl-50.json`](docs/benchmarks/litsearch-inline-acl-50.json), with [raw BM25 results](docs/benchmarks/bm25_title_abstract_inline_acl_50.jsonl) and their [hash manifest](docs/benchmarks/bm25_title_abstract_inline_acl_50.summary.json).\n\n
\n\n## Citation graph and paper library\n\n![Real paper-library graph](docs/assets/paper-library-graph.svg)\n\nRendered from a live local collection, the graph reveals foundations, bridges, and the papers that move a field forward. Stable identities and parallel citation traversal keep the map connected as it grows.\n\nThe paper library uses one persistent SQLite authority with WAL transactions and FTS5 search. Existing JSONL collections migrate automatically and remain available as compatibility snapshots. Stable identifiers, notes, tags, PDF paths, connector IDs, and sync revisions stay attached to the same canonical record.\n\nDefault data layout:\n\n```text\n~/.scholar-mcp/\n├── papers/ persistent PDFs\n├── kb/\n│ ├── library.sqlite3 authority + FTS5 + sync state\n│ └── *.jsonl compatibility snapshots\n└── vault/ Markdown projections and wikilinks\n```\n\n### Library connectors\n\n```bash\n# No login: write directly into an Obsidian vault\nscholar-mcp library export obsidian --collection rag --path /path/to/vault\n\n# Dry-run by default; add --apply for external writes\nscholar-mcp library sync zotero --collection rag\nscholar-mcp library publish notion --collection rag\n```\n\n[Obsidian](https://help.obsidian.md/Files+and+folders/Manage+vaults) is a live Markdown projection. [Zotero](https://www.zotero.org/support/dev/web_api/v3/write_requests) manages bibliographic items, collections, tags, and notes. [Notion](https://developers.notion.com/reference/post-page) receives a one-way reading-list view. External connectors keep their IDs, versions, and content hashes in SQLite, so unchanged papers do not publish twice.\n\n## Paper access\n\n`read_paper` uses a temporary PDF and reads pages 1-10 by default, which usually reaches the conclusion of an AI conference paper. It returns page-aware Markdown, structured tables when their geometry is reliable, and caption selectors for figures and visual table fallbacks. Pass `visual=\"Figure 3\"` or another returned selector to receive one focused page crop alongside its text. Pass `pages=\"11-20\"` to continue into references or appendices. The PDF is removed after extraction. `download_paper` streams into a staging file, atomically publishes a validated PDF, reuses a valid local copy, and indexes its metadata in the selected collection.\n\nThe shared resolution chain covers:\n\n1. Native open-access records and canonical archives such as arXiv and Europe PMC\n2. Registered repository resolvers: CORE, OpenAIRE, HAL, Zenodo, and DOAJ\n3. bioRxiv, medRxiv, SSRN, ChemRxiv, and other preprint servers\n4. Unpaywall and an optional institutional proxy\n5. an explicit local fallback when enabled\n\n`scholar-mcp sources` prints the live registry-derived capability matrix. Zenodo participates in PDF resolution but stays out of default discovery because its broad publication records add more candidate noise than retrieval value.\n\n## Configuration\n\nAll credentials are optional and remain in the MCP process environment.\n\n| Variable | Purpose |\n|---|---|\n| `SCHOLAR_DATA_DIR` | Shared data root; default `~/.scholar-mcp` |\n| `SCHOLAR_KB_DIR` | SQLite library and JSONL snapshot directory |\n| `SCHOLAR_OBSIDIAN_VAULT` | Obsidian projection root; no authentication required |\n| `S2_API_KEY` / `S2_API_KEYS` | Semantic Scholar search, snippets, graph, and rate limits |\n| `OPENALEX_API_KEY` / `OPENALEX_API_KEYS` | OpenAlex search, semantic search, and graph calls |\n| `OPENALEX_EMAIL` | OpenAlex polite pool and Unpaywall |\n| `DASHSCOPE_API_KEY` | Qwen reranker |\n| `SCOPUS_API_KEY` | Optional Scopus metadata source |\n| `CORE_API_KEY` | Optional CORE repository source |\n| `EXA_API_KEY` | Optional Exa research-paper source |\n| `OPENREVIEW_USERNAME`, `OPENREVIEW_PASSWORD` | OpenReview API |\n| `SCHOLAR_SOURCE_BUDGET_S` | Initial source fan-out budget; default 8 seconds |\n| `SCHOLAR_DOWNLOAD_DIR` | Persistent PDF directory; default `/papers` |\n| `SCHOLAR_MCP_EXTENSIONS` | Use `research` for graph and paper-library tools |\n| `ZOTERO_API_KEY`, `ZOTERO_LIBRARY_ID` | Zotero Web API or authorized local API connector |\n| `ZOTERO_LIBRARY_TYPE`, `ZOTERO_API_BASE` | Optional Zotero library type and endpoint override |\n| `NOTION_API_KEY`, `NOTION_DATA_SOURCE_ID` | Notion one-way publisher |\n\nErrors returned to the model redact request URLs and credentials.\n\n## Development\n\n```bash\ngit clone https://github.com/Liyux3/scholar-mcp.git\ncd scholar-mcp\nuv sync --extra dev\nuv run pytest\n```\n\nUnit tests are the default. Live API tests are marked `integration` and run separately with `uv run pytest -m integration`; pytest reports them as `deselected` during the deterministic unit run because the marker filter intentionally leaves network-dependent cases out of that invocation.\n\nConnector and feature contributions follow [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues through the private process in [SECURITY.md](SECURITY.md); citation metadata is available in [CITATION.cff](CITATION.cff).\n\nLocal and Docker clients use stdio by default. Set `SCHOLAR_MCP_TRANSPORT=http` for Streamable HTTP; the default endpoint is `/mcp`.\n\n## License\n\nApache License 2.0\n", "bytes": 13870, "sha": "29d0a64b76f7887315e74c5b2a108656221a7c45bcdb6d73717f71e12f7d6cd6", "repo_slug": "liyux3/scholar-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_liyux3_scholar_mcp_5b15d3a6/readme" }