Skip to content
Back to search

paper-search-mcp

MCP, CLI, Skills for searching and downloading academic papers from multiple sources like arXiv, PubMed, bioRxiv, etc.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openags--paper-search-mcp/badge.svg)](/listings/openags--paper-search-mcp)

HTML

<a href="/listings/openags--paper-search-mcp"><img src="/api/listings/openags--paper-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Choose the method that best fits your workflow. All methods support the same [optional API keys](#credential--api-key-requirements).

---

Claude Code (Skill) — recommended for Claude Code users

Install as a Claude Code skill instead of an MCP server. This gives Claude automatic access to paper search when you mention finding papers, academic literature, etc. — no MCP configuration needed.

**Prerequisites**: [uv](https://docs.astral.sh/uv/getting-started/installation/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview).

**Step 1 — Install the CLI:**

uv tool install paper-search-mcp

**Step 2 — Install the skill:**

mkdir -p ~/.claude/skills/paper-search
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/claude-code/SKILL.md \
  -o ~/.claude/skills/paper-search/SKILL.md

**Step 3 (optional) — Configure API keys:**

Create `~/.config/paper-search-mcp/.env` for optional API keys (see [Environment Variables](#environment-variables-env-file)).

**That's it.** Next time you start Claude Code, just ask it to find papers — the skill activates automatically. For example:

- "Find me recent papers on CRISPR base editing" - "Search arxiv and semantic scholar for transformer attention mechanisms" - "Download the PDF for arxiv paper 2106.12345"

The skill uses a CLI (`paper-search`) that wraps the same library as the MCP server, outputting JSON for search/download and plain text for read.

`paper-search download` reports `status: "ok"` only when the returned path is a readable, non-empty regular file with a PDF header. Connector error strings, missing files, and saved HTML error pages produce a JSON error and exit code 1. This lightweight check does not establish complete PDF integrity or paper identity; those checks remain the responsibility of the source connector and the reader.

Choose sources explicitly when latency matters:

paper-search search "gender imbalance neuroscience references" -s fast -n 3
paper-search search "gender imbalance neuroscience references" -s fastest -n 3
paper-search search "gender imbalance neuroscience references" -s all -n 3
paper-search download semantic DOI:10.1038/s41593-020-0658-y -o ./downloads

The CLI keeps `-s all` as its default broad source set. `--exhaustive` is an accepted compatibility no-op because broad search is already the default. Explicit `-s` selections always take precedence, including `-s fast` and `-s fastest`. The broad preset includes the supported public sources; optional paid sources are never added to these presets.

`-s fast` selects OpenAlex, Crossref, arXiv, PubMed, and Europe PMC. A nonblank `PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY` (or legacy `SEMANTIC_SCHOLAR_API_KEY`) also includes Semantic Scholar. `-s fastest` selects only OpenAlex and Crossref. Presets are latency-oriented choices, not guarantees of response time or exhaustive literature coverage. Anonymous Semantic Scholar 429 responses fail immediately; authenticated requests retain bounded retries.

Only selected searchers are constructed. Source lists and presets are honored exactly: a DOI in the query never adds another source. Use `-s unpaywall` for a DOI lookup, or include `unpaywall` explicitly in a comma-separated source list. The broad `all` preset already includes it. MCP server search defaults are unchanged.

To stop a slow source from holding up a CLI search, opt into a per-source deadline:

paper-search search "robot scientist" -s fast --source-timeout 45

`--source-timeout SECONDS` must be positive and finite. It runs selected sources in separate Python processes, at most four at once. Each source's budget starts after OS process creation returns and includes Python/provider initialization, search, serialization, and worker exit. Process creation, time waiting for a worker slot, and process cleanup add overhead outside that budget. It is

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 838 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Paper Search MCP
  2. A Model Context Protocol (MCP) server for searching and downloading academic papers from multiple sources. The project follows a free-first strategy: prioritize open and public data sources, support optional API keys when they improve stability or coverage, and keep source-specific connectors extensible for advanced users.
  3. ![PyPI](https://img.shields.io/pypi/v/paper-search-mcp.svg) ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
  4. [![smithery badge](https://smithery.ai/badge/@openags/paper-search-mcp)](https://smithery.ai/server/@openags/paper-search-mcp)
  5. ---
  6. ## Table of Contents
  7. - [Overview](#overview)
  8. - [Project Principles](#project-principles)
  9. - [MCP Authorization Compatibility](#mcp-authorization-compatibility)
  10. - [Features](#features)
  11. - [Source Strategy](#source-strategy)
  12. - [Sci-Hub Notice](#sci-hub-notice)
  13. - [Installation](#installation)
  14. - [Claude Code (Skill)](#claude-code-skill--recommended-for-claude-code-users)
  15. - [Method 1 — Smithery](#method-1--smithery-one-command-recommended-for-claude-desktop)
  16. - [Method 2 — uvx](#method-2--uvx-no-install-always-latest)
  17. - [Method 3 — uv](#method-3--uv-persistent-install)
  18. - [Method 4 — pip](#method-4--pip-standard-python-install)
  19. - [Method 5 — npx](#method-5--npx-via-smithery-cli-no-local-python-needed)
  20. - [Method 6 — Docker](#method-6--docker)
  21. - [Method 7 — Clone & run from source](#method-7--clone--run-from-source-development--recommended-for-macos-local)
  22. - [DeepSeek Harness (DSH)](#deepseek-harness-dsh)
  23. - [Environment Variables](#environment-variables-env-file)
  24. - [Contributing](#contributing)
  25. - [Demo](#demo)
  26. - [Star History](#star-history)
  27. - [License](#license)
  28. - [TODO](#todo)
  29. ---
  30. ## Overview
  31. `paper-search-mcp` is a Python-based tool for searching and downloading academic papers from various platforms. It provides tools for searching papers, downloading PDFs, and extracting text, making it ideal for researchers and AI-driven workflows. It can be used as an MCP server (for Claude Desktop and other MCP clients) or as a Claude Code skill with a CLI interface.
  32. ## Project Principles
  33. - **Free-First**: Public and open sources are the default roadmap. Paid or restricted sources are not the core direction of this project.
  34. - **Optional API Keys**: API keys are supported only when they improve stability, rate limits, or metadata quality. The MCP should still be usable without them whenever possible.
  35. - **LLM-Friendly Retrieval**: Search results should be standardized, deduplicated, and as complete as possible for downstream LLM workflows.
  36. - **Source Transparency**: Different sources have different strengths. The MCP should make those tradeoffs explicit instead of pretending every source supports full-text retrieval.
  37. ---
  38. ## MCP Authorization Compatibility
  39. The bundled MCP server supports `stdio` (the default), `sse`, and `streamable-http`. Network transports bind to `127.0.0.1` by default. Optional OAuth protected-resource mode adds standard discovery, JWT bearer-token validation and required scopes to both HTTP transports, using an external authorization server.
  40. Enable it with `--auth oauth` or `PAPER_SEARCH_MCP_AUTH=oauth` and the explicit issuer/JWKS/resource/audience/scope configuration in [OAuth protected-resource setup](docs/OAUTH_PROTECTED_RESOURCE.md). Invalid or incomplete HTTP auth settings fail startup. stdio remains independent of HTTP authentication. Local HTTP without OAuth configuration remains open; do not publish that listener directly. A protected remote deployment still needs TLS, rate limits and filesystem isolation. This feature does not host login/accounts or replace the external issuer's OAuth flow; live identity-provider interoperability must be validated for your deployment.
  41. ---
  42. ## Features
  43. - **Two-Layer Architecture**:
  44. - **Layer 1 (Unified Tooling)**: High-level `search_papers` for multi-source concurrent search & deduplication, and `download_with_fallback` relying on publisher open access links with sequential fallbacks.
  45. - **Layer 2 (Platform Connectors)**: Modular connectors for specific academic platforms (arXiv, PubMed, bioRxiv, Semantic Scholar, etc.) equipped with intelligent DOI extraction via regex text analysis or API fields.
  46. - **Multi-Source Support**: Search and download papers from arXiv, PubMed, bioRxiv, medRxiv, Google Scholar, IACR ePrint Archive, Semantic Scholar, Crossref, OpenAlex, PubMed Central (PMC), CORE, Europe PMC, dblp, OpenAIRE, CiteSeerX, DOAJ, BASE, Zenodo, HAL, SSRN, OpenReview, Unpaywall (DOI lookup), and optional Sci-Hub workflows.
  47. - **Opt-in Fast Search**: CLI search keeps broad coverage by default. Use `-s fast` (OpenAlex, Crossref, arXiv, PubMed, Europe PMC) or `-s fastest` (OpenAlex and Crossref) when lower latency matters more than coverage.
  48. - **Standardized Output**: Papers are returned in a consistent dictionary format via the `Paper` class.
  49. - **Free-First Design**: Open and public sources are prioritized before any optional commercial or restricted integrations.
  50. - **Optional API-Key Enhancement**: Sources like Semantic Scholar can work better with a user-provided API key, but are not intended to force paid usage.
  51. - **Discovery + Retrieval Workflow**: Google Scholar and Crossref can be used for discovery and DOI backfilling, while open repositories and publisher links are used for lawful full-text resolution where available.
  52. - **OA-First Fallback Chain**: `download_with_fallback` now follows source-native download → OpenAIRE/CORE/Europe PMC/PMC discovery → Unpaywall DOI resolution → optional Sci-Hub.
  53. - **Bounded reference lookups**: [OpenAlex references and citing papers](docs/OPENALEX_RELATIONSHIPS.md) from a DOI or OpenAlex ID, with explicit budgets and truncation metadata.
  54. - **MCP Integration**: Compatible with MCP clients for LLM context enhancement.
  55. - **DeepSeek Harness (DSH) Integration**: A dsh profile bundle (clone the repo, `npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add link:./dsh`) exposing every tool as `mcp__paper-search__*`, with an optional guidance skill.
  56. - **Extensible Design**: Easily add new academic platforms by extending the `academic_platforms` module.
  57. ## Source Strategy
  58. The long-term goal is not to depend on a single search engine, but to combine multiple free and public sources with clear roles:
  59. - **Open metadata backbone**: Crossref, OpenAlex, Semantic Scholar, dblp, CiteSeerX, SSRN, Unpaywall (DOI-centric OA metadata).
  60. - **Discipline-specific sources**: arXiv, PubMed, PubMed Central, Europe PMC, IACR.
  61. - **Open-access full-text sources**: arXiv, PMC, CORE, OpenAIRE, DOAJ, BASE, Zenodo, HAL, publisher open-access links.
  62. - **Discovery and DOI recovery**: Google Scholar can be useful for finding titles, versions, and DOI clues when other public metadata sources are incomplete.
  63. Recommended free-first roadmap:
  64. 1. Keep current public sources stable.
  65. 2. Add OpenAlex as a broad free metadata source.
  66. 3. Add PubMed Central and Europe PMC for stronger biomedical full-text access.
  67. 4. Add CORE and OpenAIRE for repository-based open-access retrieval.
  68. 5. Use Google Scholar mainly as a discovery fallback, not as the primary canonical source.
  69. ## Platform Capability Matrix
  70. This matrix reflects **verified live-integration results** from functional and end-to-end regression tests in this repository. Columns show the highest capability level observed under normal conditions.
  71. | Platform | Search | Download | Read | Notes |
  72. |---|---|---|---|---|
  73. | arXiv | ✅ | ✅ | ✅ | Open API; reliable |
  74. | PubMed | ✅ | ❌ | ⚠️ info-only | Open API; reliable |
  75. | bioRxiv | ✅ | ✅ | ✅ | Open API; reliable |
  76. | medRxiv | ✅ | ✅ | ✅ | Open API; reliable |
  77. | Google Scholar | ⚠️ | ❌ | ❌ | Upstream bot-detection/rate limits can prevent search; reported as source errors |
  78. | IACR | ✅ | ✅ | ✅ | Open API; reliable |
  79. | Semantic Scholar | ✅ | ✅ (OA) | ✅ (OA) | Works without key (rate-limited); key improves limits; key rejection (403) retried automatically without key |
  80. | Crossref | ✅ | ❌ | ⚠️ info-only | Open API; reliable |
  81. | OpenAlex | ✅ | ❌ | ⚠️ info-only | Open API; free API key improves daily limits |
  82. | PMC | ✅ | ✅ (OA only) | ✅ (OA only) | OA PDFs only; direct download may be blocked by some proxy environments |
  83. | CORE | ✅ | ✅ (record-dependent) | ✅ (record-dependent) | Free key recommended; connector retries with backoff and falls back to key-less on 401/403 |
  84. | Europe PMC | ✅ | ✅ (OA) | ✅ (OA) | OA PDFs only; direct download may be blocked by some proxy environments |
  85. | dblp | ✅ | ❌ | ⚠️ info-only | Open API; reliable |
  86. | OpenAIRE | ✅ | ❌ | ❌ | Open API; retries 3× with escalating request profiles on transient 403 |
  87. | CiteSeerX | ⚠️ | ✅ (record-dependent) | ⚠️ | API endpoint intermittently unavailable / redirects to web archive |
  88. | DOAJ | ✅ | ⚠️ (URL-dependent) | ⚠️ (URL-dependent) | PDF availability varies by article; free key raises rate limits |
  89. | BASE | ⚠️ | ✅ (record-dependent) | ✅ (record-dependent) | OAI-PMH endpoint requires institutional IP registration; returns empty gracefully otherwise |
  90. | Zenodo | ✅ | ✅ (record-dependent) | ✅ (record-dependent) | Open API; reliable |
  91. | HAL | ✅ | ✅ (record-dependent) | ✅ (record-dependent) | Open API; reliable |
  92. | SSRN | ✅ (OpenAlex metadata) | ⚠️ best-effort | ⚠️ best-effort | Public discovery verified; SSRN page/PDF identity must be verified separately |
  93. | OpenReview | ✅ (anonymous API v2) | ⚠️ public-only | ⚠️ public-only | Search verified; exact-note lookup returned 403 in live PDF check; PDF success is mock-tested only |
  94. | Unpaywall | ✅ (DOI lookup) | ❌ | ❌ | **Requires** `PAPER_SEARCH_MCP_UNPAYWALL_EMAIL` |
  95. | Sci-Hub (optional) | ⚠️ fallback-only | ✅ | ❌ | Optional; unstable mirrors; user responsibility |
  96. | **IEEE Xplore** 🔑 | ⚠️ configured metadata | ❌ | ❌ | Deterministic tests only; no live key-authenticated validation; metadata key does not grant full text |
  97. | **ACM DL** | ✅ (Crossref metadata) | ⚠️ | ⚠️ | Keyless search; direct PDF/read may be blocked by browser challenges; use OA fallback |
  98. > ✅ = reliable in live tests. ⚠️ = works but subject to upstream instability or access restrictions. ❌ = not supported. 🔑 = key required. 🚧 = skeleton only.
  99. ---
  100. ## Credential & API Key Requirements
  101. All keys are **optional** unless noted. Configure them in `~/.config/paper-search-mcp/.env` (preferred) or as shell exports.
  102. | Environment Variable | Provider | Required? | How to obtain |
  103. |---|---|---|---|
  104. | `PAPER_SEARCH_MCP_UNPAYWALL_EMAIL` | Unpaywall | **Yes** (Unpaywall disabled without it) | Any valid email; register at [unpaywall.org](https://unpaywall.org/products/api) |
  105. | `PAPER_SEARCH_MCP_CORE_API_KEY` | CORE | Recommended | Free at [core.ac.uk/services/api](https://core.ac.uk/services/api) |
  106. | `PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY` | Semantic Scholar | Optional | Free at [semanticscholar.org](https://www.semanticscholar.org/product/api) — improves rate limits |
  107. | `PAPER_SEARCH_MCP_OPENALEX_API_KEY` | OpenAlex | Optional | Free at [openalex.org/settings/api](https://openalex.org/settings/api); increases the keyless daily budget 10x |
  108. | `PAPER_SEARCH_MCP_OPENALEX_EMAIL` | OpenAlex | Optional | Contact email used in the OpenAlex `User-Agent` |
  109. | `PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL` | Google Scholar | Optional | Your HTTP/HTTPS proxy URL; does not guarantee access or remove provider limits |
  110. | `PAPER_SEARCH_MCP_DOAJ_API_KEY` | DOAJ | Optional | Free at [doaj.org](https://doaj.org/apply-for-api-key/) — raises hourly rate limit |
  111. | `PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN` | Zenodo | Optional | Free at [zenodo.org](https://zenodo.org/account/settings/applications/) — required for private records |
  112. | `PAPER_SEARCH_MCP_IEEE_API_KEY` | IEEE Xplore | **Required to activate** | Free at [developer.ieee.org](https://developer.ieee.org/) |
  113. All variables follow the `PAPER_SEARCH_MCP_<NAME>` prefix scheme. Legacy names without the prefix (e.g. `CORE_API_KEY`, `UNPAYWALL_EMAIL`) are still supported for backward compatibility.
  114. ---
  115. ## Known Upstream Limitations
  116. Some search failures are caused by external provider instability, not by bugs in this project:
  117. | Source | Symptom | Cause | Workaround |
  118. |---|---|---|---|
  119. | Google Scholar | Source error for HTTP/network failures, CAPTCHA, or persistent consent pages | Upstream rate limits, access checks, or connectivity | Reduce request frequency or use another public source; CAPTCHA is not solved automatically |
  120. | Semantic Scholar | 429 rate-limited responses | Anonymous access rate limit | Set `PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY`; if key is rejected (403) connector automatically retries without key |
  121. | OpenAlex | 403/429 or daily quota errors | Anonymous access daily limit | Set `PAPER_SEARCH_MCP_OPENALEX_API_KEY` |
  122. | CORE | 500 / timeout errors | Unauthenticated rate limiting | Set `PAPER_SEARCH_MCP_CORE_API_KEY` (free); connector retries with exponential backoff and falls back to key-less on 401/403 |
  123. | OpenAIRE | Transient 403 responses | IP-based session rate limiting | Connector retries 3× per profile, escalating: plain session → XML Accept header → raw `requests.get` with Mozilla UA |
  124. | CiteSeerX | 404 via web archive redirect | PSU endpoint intermittently redirects to archive | No workaround; connector returns empty gracefully |
  125. | BASE | Search returns 0 results | OAI-PMH endpoint requires institutional IP registration | Register at [base-search.net](https://www.base-search.net/about/en/) for API access; connector returns empty gracefully otherwise |
  126. | SSRN full text | HTTP 403 or identity unavailable | Public page/PDF delivery may be restricted | Search uses OpenAlex; download reports failure without login, redirects or HTML search fallback |
  127. | PMC / Europe PMC | PDF download ProxyError | Local proxy blocking direct HTTPS PDF download | Disable proxy or use `download_with_fallback` instead |
  128. | Unpaywall | Skipped entirely | `UNPAYWALL_EMAIL` env var not set | Set `PAPER_SEARCH_MCP_UNPAYWALL_EMAIL` in `~/.config/paper-search-mcp/.env` |
  129. Google Scholar failures are exposed in `errors.google_scholar` by unified MCP
  130. and CLI search, while successful sources still return their papers. Direct
  131. Scholar searches raise `GoogleScholarSearchError` for those failures. A normal
  132. empty result page still returns an empty list. If a later page fails, the source
  133. is reported as failed rather than returning its earlier pages as complete.
  134. Timeouts also raise a source error rather than implying that no papers exist.
  135. After exhausted HTTP 403/429/503 retries or a CAPTCHA, the shared Scholar
  136. connector enters a 60-second cooldown. Consecutive blocked searches extend it
  137. exponentially up to 15 minutes; a valid upstream `Retry-After` can extend this
  138. interval. A successful page resets the streak. Calls during cooldown fail
  139. immediately with a retry interval and do not contact Scholar. Retries honor
  140. valid `Retry-After` seconds or HTTP dates up to 24 hours. Longer instructions
  141. pause automatic requests for the lifetime of this connector instead of retrying
  142. earlier than the provider requested. Delays above 30 seconds are carried across
  143. calls without sleeping in a worker. Concurrent calls share the same paced session. The connector does not rotate
  144. identity between requests or solve CAPTCHAs. Cooldown state is process-local,
  145. not a guarantee of an upstream quota or recovery after that interval.
  146. For a survey, select alternative sources explicitly, for example MCP
  147. `search_papers(query, sources="google_scholar,openalex,semantic,crossref")` or CLI
  148. `paper-search search "query" -s google_scholar,openalex,semantic,crossref`.
  149. Successful providers keep their own source labels and their papers even when
  150. Scholar is cooling down. Alternatives have their own access/rate limits; they
  151. are never silently returned as Google Scholar results.
  152. ## Local PDF section extraction
  153. `extract_sections` splits an already-downloaded PDF at recognized standalone
  154. headings, preserving extracted text order and page spans with explicit limits
  155. and truncation. Reads are confined to the configured download root; no network,
  156. OCR, medical inference or new dependency is added. Labels are heuristic and may
  157. be uncertain. See [bounded PDF sections](docs/PDF_SECTIONS.md) for access rules,
  158. CLI usage and parser limitations.
  159. ### arXiv PDF downloads and reads
  160. arXiv downloads validate bare modern/legacy paper IDs, serialize and pace requests,
  161. check HTTP status, stream at most 100 MiB to a same-directory temporary file, and
  162. check the PDF header and parser before atomically replacing the destination.
  163. A failed transfer or invalid PDF leaves an existing file unchanged. Downloads
  164. use 10-second connect and 30-second read timeouts, not a hard total transfer
  165. or parser runtime limit, and do not automatically retry denied responses.
  166. `read arxiv` reports invalid/encrypted/image-only PDFs as errors rather than
  167. successful empty output; it does not perform OCR or delete invalid cached files.
  168. ## Optional Paid Platform Connectors (Phase 3)
  169. IEEE Xplore provides **opt-in metadata search**, disabled until an existing API key is configured.
  170. ACM Digital Library search is **keyless and enabled by default**, using Crossref metadata restricted to ACM DOI prefix `10.1145`.
  171. | Platform | Env Var | Status |
  172. |---|---|---|
  173. | IEEE Xplore | `PAPER_SEARCH_MCP_IEEE_API_KEY` | Metadata search with pagination; direct download/read remain unsupported |
  174. | ACM Digital Library | None | Crossref-backed search; PDF download/read depend on publisher access |
  175. **How to enable:**
  176. ```bash
  177. export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key> # free key at https://developer.ieee.org/
  178. ```
  179. With an IEEE key, `ieee` and its tools are registered at startup. See [IEEE metadata limits and full-text boundaries](docs/IEEE_METADATA.md). ACM (`acm`, `search_acm`, `download_acm`, and `read_acm_paper`) is always available. Legacy `PAPER_SEARCH_MCP_ACM_API_KEY` / `ACM_API_KEY` settings are no longer used and can be removed.
  180. ACM downloads require an ACM DOI such as `10.1145/...`. Publisher browser challenges may block scripted access; use `download_with_fallback(source="acm", paper_id="10.1145/...", doi="10.1145/...")` to try open repositories. `read_acm_paper` downloads a PDF into `save_path` before extracting text and can overwrite that file.
  181. ## Free Source Expansion (Phase 4)
  182. Additional public-source connectors are integrated into the MCP server:
  183. - `zenodo`: Official Zenodo REST API connector (search + record-dependent PDF/read support).
  184. - `hal`: HAL public API connector (search + record-dependent PDF/read support).
  185. - `ssrn`: [OpenAlex-backed discovery](docs/SSRN_OPENALEX.md) with strict SSRN identity and validated best-effort public downloads.
  186. - `openreview`: [Anonymous public API v2 papers](docs/OPENREVIEW.md), excluding reviews/private notes; verified OpenReview-hosted PDF download/read.
  187. - `unpaywall`: DOI-centric OA metadata source for standalone lookup (`search_unpaywall`) and fallback URL resolution.
  188. SSRN integration remains compliance-first: it only attempts direct public PDF links exposed by SSRN pages. If login/restricted delivery is required, the connector returns a clear message instead of bypassing access controls.
  189. ## Sci-Hub Notice
  190. Sci-Hub support can remain available as an optional connector for users who explicitly choose to enable it, but it should not be treated as the default or recommended full-text path.
  191. - `download_with_fallback` leaves Sci-Hub disabled by default. Pass `use_scihub=true` only when you explicitly choose to use it.
  192. - Availability is unstable and mirrors change frequently.
  193. - Legal and policy risks vary by jurisdiction.
  194. - README and tool descriptions should clearly state that users are responsible for enabling and using it.
  195. - Open-access and publisher-permitted sources should be tried first whenever possible.
  196. ---
  197. ## Installation
  198. Choose the method that best fits your workflow. All methods support the same [optional API keys](#credential--api-key-requirements).
  199. ---
  200. ### Claude Code (Skill) — recommended for Claude Code users
  201. Install as a Claude Code skill instead of an MCP server. This gives Claude automatic access to paper search when you mention finding papers, academic literature, etc. — no MCP configuration needed.
  202. **Prerequisites**: [uv](https://docs.astral.sh/uv/getting-started/installation/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview).
  203. **Step 1 — Install the CLI:**
  204. ```bash
  205. uv tool install paper-search-mcp
  206. ```
  207. **Step 2 — Install the skill:**
  208. ```bash
  209. mkdir -p ~/.claude/skills/paper-search
  210. curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/claude-code/SKILL.md \
  211. -o ~/.claude/skills/paper-search/SKILL.md
  212. ```
  213. **Step 3 (optional) — Configure API keys:**
  214. Create `~/.config/paper-search-mcp/.env` for optional API keys (see [Environment Variables](#environment-variables-env-file)).
  215. **That's it.** Next time you start Claude Code, just ask it to find papers — the skill activates automatically. For example:
  216. - "Find me recent papers on CRISPR base editing"
  217. - "Search arxiv and semantic scholar for transformer attention mechanisms"
  218. - "Download the PDF for arxiv paper 2106.12345"
  219. The skill uses a CLI (`paper-search`) that wraps the same library as the MCP server, outputting JSON for search/download and plain text for read.
  220. `paper-search download` reports `status: "ok"` only when the returned path is a
  221. readable, non-empty regular file with a PDF header. Connector error strings,
  222. missing files, and saved HTML error pages produce a JSON error and exit code 1.
  223. This lightweight check does not establish complete PDF integrity or paper identity;
  224. those checks remain the responsibility of the source connector and the reader.
  225. Choose sources explicitly when latency matters:
  226. ```bash
  227. paper-search search "gender imbalance neuroscience references" -s fast -n 3
  228. paper-search search "gender imbalance neuroscience references" -s fastest -n 3
  229. paper-search search "gender imbalance neuroscience references" -s all -n 3
  230. paper-search download semantic DOI:10.1038/s41593-020-0658-y -o ./downloads
  231. ```
  232. The CLI keeps `-s all` as its default broad source set. `--exhaustive` is an
  233. accepted compatibility no-op because broad search is already the default.
  234. Explicit `-s` selections always take precedence, including `-s fast` and
  235. `-s fastest`. The broad preset includes the supported public sources;
  236. optional paid sources are never added to these presets.
  237. `-s fast` selects OpenAlex, Crossref, arXiv, PubMed, and Europe PMC. A nonblank
  238. `PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY` (or legacy
  239. `SEMANTIC_SCHOLAR_API_KEY`) also includes Semantic Scholar. `-s fastest` selects
  240. only OpenAlex and Crossref. Presets are latency-oriented choices, not guarantees
  241. of response time or exhaustive literature coverage. Anonymous Semantic Scholar
  242. 429 responses fail immediately; authenticated requests retain bounded retries.
  243. Only selected searchers are constructed. Source lists and presets are honored
  244. exactly: a DOI in the query never adds another source. Use `-s unpaywall` for a
  245. DOI lookup, or include `unpaywall` explicitly in a comma-separated source list.
  246. The broad `all` preset already includes it. MCP server search defaults are
  247. unchanged.
  248. To stop a slow source from holding up a CLI search, opt into a per-source deadline:
  249. ```bash
  250. paper-search search "robot scientist" -s fast --source-timeout 45
  251. ```
  252. `--source-timeout SECONDS` must be positive and finite. It runs selected sources
  253. in separate Python processes, at most four at once. Each source's budget starts
  254. after OS process creation returns and includes Python/provider initialization,
  255. search, serialization, and worker exit. Process creation, time waiting for a
  256. worker slot, and process cleanup add overhead outside that budget. It is
  257. not a deadline for the whole command. Timed-out workers are killed and reaped
  258. before their slots are reused, so a blocked network call cannot hold up Python's
  259. thread-executor shutdown. Successful sources keep their results and timed-out
  260. sources appear in `errors` with a zero `source_results` count. Source selection,
  261. labels, sorting, JSON fields, and partial-result exit status (0) are unchanged.
  262. Subprocess startup adds overhead, especially for very small budgets. Without the
  263. flag, existing connector-specific timeouts and in-process search are unchanged.
  264. Sort search results by citation count or publication date:
  265. ```bash
  266. paper-search search "transformer attention" --sources arxiv,semantic --sort citations
  267. paper-search search "CRISPR" --sort date
  268. ```
  269. `--sort relevance` (the default) preserves the existing order: selected sources
  270. in order, with each source's returned order unchanged. It does not compute a
  271. cross-source relevance score. `--sort citations` orders highest counts first;
  272. `--sort date` orders newest publication dates first. Sorting is client-side,
  273. after deduplication, and only covers retrieved results (`--max-results` is per
  274. source); it does not change source queries or search the full source collection
  275. for its most-cited/newest papers. Ties retain their original order. Missing or
  276. invalid values sort last; numeric citation strings are supported. Dates accept
  277. ISO dates/timestamps, with naive timestamps and date-only values treated as UTC.
  278. The default JSON output and selected sources are unchanged.
  279. #### MCP tools from the CLI
  280. `paper-search tool` calls the same registered tools as the MCP server, including
  281. source-specific options and DOI lookup. Required arguments are positional;
  282. optional arguments use kebab-case flags. Boolean flags use `--flag` and
  283. `--no-flag`; omitted options retain their MCP defaults.
  284. ```bash
  285. paper-search tool --help
  286. paper-search tool --list # JSON tool list, schemas, and annotations
  287. paper-search tool search_crossref --help
  288. paper-search tool search_crossref "transformer attention" --filter from-pub-date:2024-01-01 --sort published --order desc --max-results 2
  289. paper-search tool get_crossref_paper_by_doi 10.1038/nature12373
  290. paper-search tool search_iacr "cryptography" --no-fetch-details
  291. ```
  292. Objects and lists return JSON; text and download paths return plain text. An
  293. exception returns a JSON error with exit code 1; invalid CLI syntax exits with
  294. code 2. A normal MCP result retains its original meaning, including error or
  295. partial-result fields returned by the tool itself. `--list` shows only tools
  296. enabled by the current configuration, so IEEE tools still require their API
  297. key. The existing `search`, `download`, `read`, and `sources` commands are
  298. unchanged. Tool calls keep the MCP tools' source selection and timeout behavior;
  299. Sci-Hub fallback remains opt-in through `--use-scihub`.
  300. #### Skill ZIP uploads and other Claude runtimes
  301. The steps above install a **local Claude Code skill** at `~/.claude/skills/paper-search/SKILL.md`, following the [Claude Code skill layout](https://code.claude.com/docs/en/skills). They do not require a ZIP upload.
  302. GitHub's **Download ZIP** contains the entire repository, with the skill nested under `paper-search-mcp-main/claude-code/`. It is not a standalone skill archive. If an uploader reports that `SKILL.md` is nested too deeply, check the archive layout first. Anthropic's [custom-skill packaging guide](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) specifies a single skill folder at the archive root, with the skill file directly inside it:
  303. ```text
  304. paper-search-skill.zip
  305. └── paper-search/
  306. └── SKILL.md
  307. ```
  308. To create that layout for inspection or adaptation, run this from a repository checkout (requires Python 3; overwrites `paper-search-skill.zip`):
  309. ```python
  310. from zipfile import ZIP_DEFLATED, ZipFile
  311. with ZipFile("paper-search-skill.zip", "w", compression=ZIP_DEFLATED) as archive:
  312. archive.write("claude-code/SKILL.md", arcname="paper-search/SKILL.md")
  313. ```
  314. A reusable builder is also available: `python scripts/build_skill_zip.py --output paper-search-skill.zip`. It refuses to overwrite an existing file unless `--force` is supplied. Its archive layout, frontmatter, and byte-for-byte instruction contents are covered by offline tests.
  315. This only packages the instructions; it does not bundle Python dependencies, install `paper-search`, or configure an MCP connection. The bundled skill expects a runtime that can execute the CLI and reach the academic services. Upload acceptance and execution in Claude web or another runtime have **not been validated by this project**. Check that runtime's current metadata, package-installation, network-access, and code-execution requirements before adapting the skill. If you want to use an MCP client instead, follow the MCP installation methods below; uploading a skill ZIP does not start or connect an external MCP server.
  316. ---
  317. > **MCP Server Config file locations** (for methods below)
  318. > - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  319. > - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  320. > - **Linux**: `~/.config/Claude/claude_desktop_config.json`
  321. ---
  322. ### Method 1 — Smithery (one-command, recommended for Claude Desktop)
  323. ```bash
  324. npx -y @smithery/cli install @openags/paper-search-mcp --client claude
  325. ```
  326. Smithery automatically writes the correct config block for you. No manual JSON editing needed.
  327. ---
  328. ### Method 2 — `uvx` (no install, always latest)
  329. `uvx` runs the package directly from PyPI without a permanent install. Requires [uv](https://docs.astral.sh/uv/getting-started/installation/).
  330. ```bash
  331. # Install uv (skip if already installed)
  332. curl -LsSf https://astral.sh/uv/install.sh | sh
  333. ```
  334. > ⚠️ **macOS note**: `uvx` generated wrapper scripts rely on `realpath`, which is not included in macOS by default. If you see a `realpath: command not found` error, either install GNU coreutils (`brew install coreutils`) or use **Method 3 (`uv run`)** instead — it does not have this limitation.
  335. **Claude Desktop config:**
  336. ```json
  337. {
  338. "mcpServers": {
  339. "paper-search-mcp": {
  340. "command": "uvx",
  341. "args": ["paper-search-mcp"],
  342. "env": {
  343. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  344. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  345. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
  346. "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
  347. "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
  348. "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
  349. }
  350. }
  351. }
  352. }
  353. ```
  354. ---
  355. ### Method 3 — `uv` (persistent install)
  356. ```bash
  357. uv tool install paper-search-mcp
  358. ```
  359. **Claude Desktop config:**
  360. ```json
  361. {
  362. "mcpServers": {
  363. "paper-search-mcp": {
  364. "command": "uv",
  365. "args": ["tool", "run", "paper-search-mcp"],
  366. "env": {
  367. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  368. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  369. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
  370. "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
  371. "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
  372. "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
  373. }
  374. }
  375. }
  376. }
  377. ```
  378. ---
  379. ### Method 4 — `pip` (standard Python install)
  380. ```bash
  381. pip install paper-search-mcp
  382. ```
  383. **Claude Desktop config:**
  384. ```json
  385. {
  386. "mcpServers": {
  387. "paper-search-mcp": {
  388. "command": "python",
  389. "args": ["-m", "paper_search_mcp.server"],
  390. "env": {
  391. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  392. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  393. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
  394. "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
  395. "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
  396. "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
  397. }
  398. }
  399. }
  400. }
  401. ```
  402. > If `python` is not on your PATH, replace it with the full path (e.g. `/usr/bin/python3` or `C:\Python311\python.exe`). Run `which python3` / `where python` to find it.
  403. ---
  404. ### Method 5 — `npx` (via Smithery CLI, no local Python needed)
  405. ```bash
  406. npx -y @smithery/cli run @openags/paper-search-mcp
  407. ```
  408. **Claude Desktop config:**
  409. ```json
  410. {
  411. "mcpServers": {
  412. "paper-search-mcp": {
  413. "command": "npx",
  414. "args": ["-y", "@smithery/cli", "run", "@openags/paper-search-mcp"],
  415. "env": {
  416. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  417. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  418. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": ""
  419. }
  420. }
  421. }
  422. }
  423. ```
  424. ---
  425. ### Method 6 — Docker
  426. ```bash
  427. docker build -t paper-search-mcp .
  428. docker run --rm -i \
  429. -e PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com \
  430. -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  431. paper-search-mcp
  432. ```
  433. **Claude Desktop config:**
  434. ```json
  435. {
  436. "mcpServers": {
  437. "paper-search-mcp": {
  438. "command": "docker",
  439. "args": ["run", "--rm", "-i", "paper-search-mcp"],
  440. "env": {
  441. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  442. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  443. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
  444. "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
  445. "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
  446. "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
  447. }
  448. }
  449. }
  450. }
  451. ```
  452. ---
  453. ### Method 7 — Clone & run from source (development / recommended for macOS local)
  454. This is the most reliable method on macOS — no wrapper scripts, no `realpath` issues.
  455. ```bash
  456. # 1. Install uv (skip if already installed)
  457. curl -LsSf https://astral.sh/uv/install.sh | sh
  458. # 2. Clone repo
  459. git clone https://github.com/openags/paper-search-mcp.git
  460. cd paper-search-mcp
  461. # 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
  462. uv run -m paper_search_mcp.server
  463. ```
  464. **Claude Desktop config** (replace the directory path with your actual clone location):
  465. ```json
  466. {
  467. "mcpServers": {
  468. "paper-search-mcp": {
  469. "command": "uv",
  470. "args": [
  471. "run",
  472. "--directory", "/path/to/paper-search-mcp",
  473. "-m", "paper_search_mcp.server"
  474. ],
  475. "env": {
  476. "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
  477. "PAPER_SEARCH_MCP_CORE_API_KEY": "",
  478. "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
  479. "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
  480. "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
  481. "PAPER_SEARCH_MCP_IEEE_API_KEY": ""
  482. }
  483. }
  484. }
  485. }
  486. ```
  487. For example, if you cloned to `/Users/mac/Pengsong/paper-search-mcp`:
  488. ```json
  489. "args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]
  490. ```
  491. > `uv run` automatically installs dependencies into an isolated environment on first run — no `pip install` or `venv` needed.
  492. To run one shared network server instead of one stdio process per client:
  493. ```bash
  494. paper-search-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp
  495. ```
  496. The available transports are `stdio`, `sse`, and `streamable-http`. The default
  497. remains `stdio`. The same network settings can be supplied with
  498. `PAPER_SEARCH_MCP_TRANSPORT`, `PAPER_SEARCH_MCP_HOST`,
  499. `PAPER_SEARCH_MCP_PORT`, and `PAPER_SEARCH_MCP_PATH`; command-line options take
  500. precedence. With the default `--auth none`, binding to a non-loopback host such
  501. as `0.0.0.0` exposes an unauthenticated server. For protected HTTP, configure
  502. [optional OAuth mode](docs/OAUTH_PROTECTED_RESOURCE.md) and keep the backend behind
  503. TLS and appropriate deployment controls; otherwise use an authenticated gateway.
  504. For active development, optionally install an editable copy:
  505. ```bash
  506. uv venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
  507. uv pip install -e ".[dev]"
  508. ```
  509. ---
  510. ### DeepSeek Harness (DSH)
  511. Paper search is available inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) as a profile bundle: it boots the MCP server and registers all its tools in any dsh profile as `mcp__paper-search__*`. The bundle only mounts a composition row — the MCP server itself is untouched.
  512. **Prerequisites**: [uv](https://docs.astral.sh/uv/getting-started/installation/) (the default launcher is `uvx`) and [pnpm](https://pnpm.io/installation) (`dsh plugin` forwards to pnpm). Commands below use the `npx @deepseek-ai/dsh` launcher (no global install needed); with a global dsh install, drop the prefix.
  513. ```bash
  514. git clone https://github.com/openags/paper-search-mcp.git
  515. cd paper-search-mcp
  516. npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add link:./dsh
  517. ```
  518. `link:` updates the bundle configuration from the checkout. `git pull` does not update the separately launched PyPI server; see `dsh/README.md` for a source-checkout launcher and reproducible version selection. Replace `web` with your profile name; a missing profile is initialized automatically. Restart the profile (`npx @deepseek-ai/dsh@0.2.0-rc.2 web`, or relaunch) and the tools appear — e.g. `mcp__paper-search__search_papers`, `mcp__paper-search__download_with_fallback`, `mcp__paper-search__search_arxiv`.
  519. **API keys**: just follow [Environment Variables](#environment-variables-env-file) — the server auto-loads `~/.config/paper-search-mcp/.env`. DSH deliberately scrubs credential-shaped ambient env vars from spawned processes, so shell exports do not reach the server; to forward variables explicitly, override the `mcp-paper-search` row in `~/.dsh/profiles/<name>/cordis.patch.yml` (a config override replaces the whole object — see `dsh/README.md` for a complete example).
  520. **Optional skill** with usage guidance (workflow, source table, tool mapping):
  521. ```bash
  522. mkdir -p ~/.dsh/skills && cp -r dsh/skills/paper-search ~/.dsh/skills/
  523. ```
  524. **Uninstall**:
  525. ```bash
  526. npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web remove paper-search-mcp-dsh
  527. rm -rf ~/.dsh/skills/paper-search
  528. ```
  529. Removing the bundle reconciles its row out of the composition. It does not delete downloaded papers, package caches, or user-managed settings.
  530. If you already run paper-search-mcp through your own `@deepseek-ai/dsh-mcp-client` row, remove that row (or give one of the two a distinct `serverName`) before adding the bundle — duplicate `serverName`s fail at load. The bundle package version tracks this checkout's Python project version; `dsh/README.md` documents alternate launchers (`uv tool run`, `python -m`, `npx`), environment forwarding, and development.
  531. ---
  532. ### Environment Variables (`.env` file)
  533. Instead of putting keys directly in the JSON config you can store them in the user config file (auto-loaded on startup):
  534. ```bash
  535. mkdir -p ~/.config/paper-search-mcp
  536. curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/.env.example \
  537. -o ~/.config/paper-search-mcp/.env
  538. $EDITOR ~/.config/paper-search-mcp/.env
  539. ```
  540. ```dotenv
  541. PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com
  542. PAPER_SEARCH_MCP_CORE_API_KEY=
  543. PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=
  544. PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN=
  545. PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL=
  546. PAPER_SEARCH_MCP_IEEE_API_KEY=
  547. ```
  548. To use a custom path: `export PAPER_SEARCH_MCP_ENV_FILE=/absolute/path/to/.env`
  549. > Legacy variable names without the `PAPER_SEARCH_MCP_` prefix (e.g. `CORE_API_KEY`, `UNPAYWALL_EMAIL`) are still supported for backward compatibility.
  550. ---
  551. ### Optional local search cache
  552. [Opt-in SQLite search caching](docs/SEARCH_CACHE.md) adds TTL, size limits,
  553. status, and clearing. It is disabled by default and bypasses authenticated sources.
  554. ## Contributing
  555. We welcome contributions! Here's how to get started:
  556. 1. **Fork the Repository**:
  557. Click "Fork" on GitHub.
  558. 2. **Clone and Set Up**:
  559. ```bash
  560. git clone https://github.com/yourusername/paper-search-mcp.git
  561. cd paper-search-mcp
  562. uv venv && source .venv/bin/activate
  563. uv pip install -e ".[dev]"
  564. ```
  565. 3. **Make Changes**:
  566. - Add new platforms in `academic_platforms/`.
  567. - Update tests in `tests/`.
  568. 4. **Submit a Pull Request**:
  569. Push changes and create a PR on GitHub.
  570. ---
  571. ## Demo
  572. <img src="docs\images\demo.png" alt="Demo" width="800">
  573. ## TODO
  574. ### Planned Academic Platforms
  575. - [√] arXiv
  576. - [√] PubMed
  577. - [√] bioRxiv
  578. - [√] medRxiv
  579. - [√] Google Scholar
  580. - [√] IACR ePrint Archive
  581. - [√] Semantic Scholar
  582. - [√] Crossref
  583. - [√] PubMed Central (PMC)
  584. - [√] CORE
  585. - [√] Europe PMC
  586. - [√] Sci-Hub warning and enablement docs
  587. ### Development Tasks
  588. - [√] Fix Async search bugs and ensure reliable fast MCP events
  589. - [√] End-to-End full pipeline testing script (search, parse, download)
  590. - [√] Establish two-layer federated architecture (Layer 1 tool: `search_papers`)
  591. - [√] Ensure pervasive DOI extraction across metadata fields & abstract fallbacks
  592. - [ ] Citation graph & Paper relation context feature
  593. - [√] Expand full-stack OpenAlex provider
  594. ### Priority Free and Open Sources
  595. - [√] PubMed Central (PMC)
  596. - [√] CORE
  597. - [√] OpenAlex
  598. - [√] Europe PMC
  599. - [√] OpenAIRE
  600. - [√] dblp
  601. - [√] CiteSeerX
  602. - [√] DOAJ
  603. - [√] BASE
  604. - [√] Zenodo
  605. - [√] HAL
  606. - [√] SSRN (discovery + best-effort full-text)
  607. - [√] Unpaywall (standalone DOI search source)
  608. ### Optional and Non-Core Integrations
  609. - [ ] ResearchGate
  610. - [ ] JSTOR
  611. - [ ] ScienceDirect
  612. - [ ] Springer Link
  613. - [√] IEEE Xplore (optional skeleton — activate with `IEEE_API_KEY`)
  614. - [√] ACM Digital Library (keyless Crossref search; publisher PDF access varies)
  615. - [ ] Web of Science
  616. - [ ] Scopus
  617. ---
  618. ## Star History
  619. [![Star History Chart](https://star-history.dera.page/svg?repos=openags/paper-search-mcp&type=Date)](https://star-history.dera.page/#openags/paper-search-mcp&Date)
  620. ---
  621. ## License
  622. This project is licensed under the MIT License. See the LICENSE file for details.
  623. ---
  624. Happy researching with `paper-search-mcp`! If you encounter issues, open a GitHub issue.
  625. ### Explicit institutional metadata connectors
  626. Web of Science Starter is available only through `search_wos` or an explicit
  627. `wos` source (`paper-search search 'TI=(machine learning)' -s wos`). Supplying a
  628. key does **not** add it to default, `all`, `fast`, or `fastest` searches. Supply
  629. `PAPER_SEARCH_MCP_WOS_API_KEY` (legacy `WOS_API_KEY` also works) at runtime; the
  630. connector does not create accounts or persist credentials. See
  631. [the institutional connector guide](docs/INSTITUTIONAL_CONNECTORS.md) for limits,
  632. errors, capability boundaries, and validation status.
  633. Scopus is likewise explicit-only (`-s scopus` or MCP `search_scopus`), using
  634. `PAPER_SEARCH_MCP_SCOPUS_API_KEY` (legacy `SCOPUS_API_KEY`). Metadata search defaults
  635. to `STANDARD`. Abstract retrieval is available via `paper-search read scopus ID`
  636. or MCP `read_scopus_paper`; ScienceDirect article retrieval requires explicit
  637. `--full-text` / `full_text=true` and a verified DOI/PII match. The response labels
  638. `full_text`, `abstract_only`, and `unavailable` separately. Neither connector's
  639. live institutional entitlement has been validated by these fixture tests.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.