openags/paper-search-mcp: MCP, CLI, Skills for searching and downloading academic papers from multiple sources like arXiv, PubMed, bioRxiv, etc.

论文检索 MCP#

这是一个基于模型上下文协议 (MCP) 的服务器，用于搜索和下载来自多个来源的学术论文。该项目遵循“免费优先”策略：优先使用开放和公共数据源，在可选 API 密钥能够提升稳定性或覆盖范围时予以支持，并保持特定数据源连接器的可扩展性，以满足高级用户的需求。

---

目录#

• 概述
• 项目原则
• 特征
• 采购策略
• 科学中心公告
• 安装
  • 克劳德代码（技能）
    • 方法一——铁匠铺
    • 方法二——uvx
    • 方法三——紫外线
    • 方法四——管道
    • 方法五——npx
    • 方法六——Docker
    • 方法 7 — 从源代码克隆并运行
    • 环境变量
• 贡献
• 演示
• 星际历史
• 执照
• 全部

---

概述#

paper-search-mcp 是一个基于 Python 的工具，用于从各种平台搜索和下载学术论文。它提供论文搜索、PDF 下载和文本提取等功能，非常适合研究人员和 AI 驱动的工作流程。它可以作为 MCP 服务器（适用于 Claude Desktop 和其他 MCP 客户端）使用，也可以作为带有命令行界面的 Claude Code 技能使用。

项目原则#

• 免费优先 ：公共和开源是默认的发展路线图。付费或受限资源并非本项目的核心方向。
• 可选 API 密钥 ：仅当 API 密钥能够提升稳定性、限制速率或提高元数据质量时才予以支持。在条件允许的情况下，MCP 仍应尽可能在不使用 API 密钥的情况下正常运行。
• LLM 友好型检索 ：搜索结果应标准化、去重，并尽可能完整，以适应下游 LLM 工作流程。
• 来源透明度 ：不同的来源各有优势。MCP 应该明确指出这些权衡取舍，而不是假装每个来源都支持全文检索。

---

特征#

• 双层架构 ：
  • 第 1 层（统一工具） ：高级 search_papers 用于多源并发搜索和去重， download_with_fallback 依赖于出版商开放获取链接，并提供顺序回退。
    • 第 2 层（平台连接器） ：针对特定学术平台（arXiv、PubMed、bioRxiv、Semantic Scholar 等）的模块化连接器，配备有通过正则表达式文本分析或 API 字段进行智能 DOI 提取的功能。
• 多源支持 ：可从 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、Unpaywall（DOI 查找）以及可选的 Sci-Hub 工作流程中搜索和下载论文。
• 标准化输出 ：论文通过 Paper 类以一致的字典格式返回。
• 免费优先设计 ：开放和公共资源优先于任何可选的商业或受限集成。
• 可选的 API 密钥增强功能 ：像 Semantic Scholar 这样的资源可以通过用户提供的 API 密钥更好地工作，但并不旨在强制付费使用。
• 发现 + 检索工作流程 ：可以使用 Google Scholar 和 Crossref 进行发现和 DOI 回填，而开放存储库和出版商链接则用于在可用时进行合法的全文解析。
• OA-First Fallback Chain: download_with_fallback 现在遵循源原生下载 → OpenAIRE/CORE/Europe PMC/PMC 发现 → Unpaywall DOI 解析 → 可选的 Sci-Hub。
• MCP 集成 ：与 MCP 客户端兼容，用于 LLM 上下文增强。
• 可扩展设计 ：通过扩展 academic_platforms 模块，轻松添加新的学术平台。

采购策略#

长远目标不是依赖单一搜索引擎，而是将多个免费公共资源结合起来，并明确它们各自的角色：

• 开放元数据骨干网 ：Crossref、OpenAlex、Semantic Scholar、dblp、CiteSeerX、SSRN、Unpaywall（以 DOI 为中心的 OA 元数据）。
• 学科特定来源 ：arXiv、PubMed、PubMed Central、Europe PMC、IACR。
• 开放获取全文来源 ：arXiv、PMC、CORE、OpenAIRE、DOAJ、BASE、Zenodo、HAL、出版商开放获取链接。
• 发现和 DOI 恢复 ：当其他公共元数据来源不完整时，Google Scholar 可用于查找标题、版本和 DOI 线索。

推荐的优先免费路线图：

1. 保持现有公共资源的稳定。
2. 添加 OpenAlex 作为广泛的免费元数据源。
3. 添加 PubMed Central 和 Europe PMC，以增强生物医学全文访问能力。
4. 添加 CORE 和 OpenAIRE，实现基于存储库的开放获取检索。
5. 主要将 Google Scholar 用作发现资料的备用途径，而不是作为主要权威来源。

平台能力矩阵#

此矩阵反映了本代码库中 经过验证的实时集成结果，这些结果 来自功能测试和端到端回归测试。各列显示了在正常条件下观察到的最高能力级别。

✅ = 实际测试可靠。 ⚠️ = 可用，但受上游不稳定或访问限制影响。❌ = 不支持。🔑 = 需要密钥。🚧 = 仅提供框架。

---

凭证和 API 密钥要求#

除非另有说明，所有键均为 可选 。请在 .env 中配置（推荐），或将其作为 shell 导出项进行配置。

所有变量均遵循 PAPER_SEARCH_MCP_<NAME> 前缀方案。为保持向后兼容性，仍支持不带前缀的旧名称（例如 CORE_API_KEY 、 UNPAYWALL_EMAIL ）。

---

已知的上游限制#

部分搜索失败是由外部服务提供商不稳定造成的，并非本项目本身存在漏洞：

可选付费平台连接器（第三阶段）#

IEEE Xplore 和 ACM 数字图书馆连接器以 可选框架的 形式提供。 默认情况下，它们处于禁用状态 ——除非您显式配置相应的密钥，否则不会进行任何 API 调用。

如何启用：

export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key>       # free key at https://developer.ieee.org/
export PAPER_SEARCH_MCP_ACM_API_KEY=<your_acm_key>         # see https://libraries.acm.org/digital-library

一旦设置了密钥，相应的源就会自动添加到 ALL_SOURCES 中，并且其 MCP 工具（ search_ieee / search_acm 、 download_ieee / download_acm 、 read_ieee_paper / read_acm_paper ）会在服务器启动时注册。

如果没有密钥，连接器只会记录启动警告——服务器的其余部分不受影响。

免费源代码扩展（第四阶段）#

MCP 服务器现在集成了三个额外的开源连接器：

• zenodo ：官方 Zenodo REST API 连接器（搜索 + 记录相关的 PDF/读取支持）。
• hal ：HAL 公共 API 连接器（搜索 + 记录相关的 PDF/读取支持）。
• ssrn ：当有直接的公共 PDF 链接可用时，具有强化解析器和尽力下载/读取的发现优先连接器。
• unpaywall ：以 DOI 为中心的 OA 元数据源，用于独立查找 ( search_unpaywall ) 和备用 URL 解析。

SSRN 集成始终以合规性为先：它仅尝试使用 SSRN 页面上公开的直接 PDF 链接。如果需要登录或受限访问，连接器会返回明确的错误信息，而不是绕过访问控制。

科学中心公告#

Sci-Hub 支持可以作为可选连接器继续供明确选择启用它的用户使用，但不应将其视为默认或推荐的全文路径。

• 可用性不稳定，镜像经常变化。
• 法律和政策风险因司法管辖区而异。
• README 文件和工具说明应明确指出，用户有责任启用和使用该工具。
• 应尽可能优先尝试开放获取和出版商允许的资源。

---

安装#

选择最适合您工作流程的方法。所有方法都支持相同的 可选 API 密钥 。

---

克劳德代码（技能）——推荐给克劳德代码用户#

安装方式为 Claude Code 技能，而非 MCP 服务器。这样，当您提及查找论文、学术文献等时，Claude 即可自动访问论文搜索功能——无需进行 MCP 配置。

先决条件 ： uv 和 Claude Code 。

第一步——克隆仓库：

git clone https://github.com/openags/paper-search-mcp.git ~/paper-search-mcp

步骤 2 — 安装技能：

mkdir -p ~/.claude/skills/paper-search
cp ~/paper-search-mcp/claude-code/SKILL.md ~/.claude/skills/paper-search/SKILL.md

步骤 3 — 更新技能中的存储库路径：

编辑 ~/.claude/skills/paper-search/SKILL.md 并将每个 <REPO_PATH> 替换为克隆的绝对路径（例如 /Users/yourname/paper-search-mcp ）。

步骤 4（可选）— 配置 API 密钥：

在仓库根目录下创建一个 .env 文件，用于存放可选的 API 密钥（请参阅 环境变量 ）。

就是这样。 下次启动克劳德代码时，只需让它查找文件——该技能会自动激活。例如：

• 请帮我查找关于 CRISPR 基因编辑的最新论文。
• “在 arXiv 和语义学者中搜索 Transformer 注意力机制”
• “下载 arXiv 论文 2106.12345 的 PDF 文件”

该技能使用 CLI（ paper-search ），它封装了与 MCP 服务器相同的库，输出 JSON 用于搜索/下载，输出纯文本用于读取。

---

MCP 服务器配置文件位置 （适用于以下方法）

• macOS ： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows ： %APPDATA%\Claude\claude_desktop_config.json
• Linux ： ~/.config/Claude/claude_desktop_config.json

---

方法一 — Smithery（单命令，推荐用于 Claude Desktop）#

npx -y @smithery/cli install @openags/paper-search-mcp --client claude

Smithery 会自动为您写入正确的配置块，无需手动编辑 JSON。

---

方法二 uvx （无需安装，始终为最新版本）#

uvx 直接从 PyPI 运行软件包，无需永久安装。需要 uv 。

# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

⚠️ macOS 注意 ： uvx 生成的包装脚本依赖于 realpath ，而 macOS 默认情况下并未包含该工具。如果您看到 realpath: command not found ”错误，请安装 GNU coreutils（ brew install coreutils ）或改用 方法 3（ uv run ） ——该方法没有此限制。

Claude 桌面配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uvx",
      "args": ["paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

---

方法 3 — uv （持久安装）#

uv tool install paper-search-mcp

Claude 桌面配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": ["tool", "run", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

---

方法四 pip （标准 Python 安装）#

pip install paper-search-mcp

Claude 桌面配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "python",
      "args": ["-m", "paper_search_mcp.server"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

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.

---

Method 5 — npx (via Smithery CLI, no local Python needed)#

npx -y @smithery/cli run @openags/paper-search-mcp

Claude Desktop config:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@openags/paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": ""
      }
    }
  }
}

---

Method 6 — Docker#

docker build -t paper-search-mcp .
docker run --rm -i \
  -e PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com \
  -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  paper-search-mcp

Claude Desktop config:

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

---

This is the most reliable method on macOS — no wrapper scripts, no realpath issues.

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repo
git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp

# 3. Verify it runs (uv auto-resolves dependencies, no manual install needed)
uv run -m paper_search_mcp.server

Claude Desktop config (replace the directory path with your actual clone location):

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/paper-search-mcp",
        "-m", "paper_search_mcp.server"
      ],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "your@email.com",
        "PAPER_SEARCH_MCP_CORE_API_KEY": "",
        "PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY": "",
        "PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN": "",
        "PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL": "",
        "PAPER_SEARCH_MCP_IEEE_API_KEY": "",
        "PAPER_SEARCH_MCP_ACM_API_KEY": ""
      }
    }
  }
}

For example, if you cloned to /Users/mac/Pengsong/paper-search-mcp:

"args": ["run", "--directory", "/Users/mac/Pengsong/paper-search-mcp", "-m", "paper_search_mcp.server"]

uv run automatically installs dependencies into an isolated environment on first run — no pip install or venv needed.

For active development, optionally install an editable copy:

uv venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

---

Environment Variables (.env file)#

Instead of putting keys directly in the JSON config you can store them in a .env file in the project root (auto-loaded on startup):

cp .env.example .env   # if running from source
# or create ~/.paper-search-mcp.env for global use

PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=your@email.com
PAPER_SEARCH_MCP_CORE_API_KEY=
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN=
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL=
PAPER_SEARCH_MCP_IEEE_API_KEY=
PAPER_SEARCH_MCP_ACM_API_KEY=

To use a custom path: export PAPER_SEARCH_MCP_ENV_FILE=/absolute/path/to/.env

Legacy variable names without the PAPER_SEARCH_MCP_ prefix (e.g. CORE_API_KEY, UNPAYWALL_EMAIL) are still supported for backward compatibility.

---

Contributing#

We welcome contributions! Here's how to get started:

1. Fork the Repository: Click "Fork" on GitHub.
2. Clone and Set Up:

   git clone https://github.com/yourusername/paper-search-mcp.git
   cd paper-search-mcp
   uv venv && source .venv/bin/activate
   uv pip install -e ".[dev]"
   

3. Make Changes:
   • Add new platforms in academic_platforms/.
     • Update tests in tests/.
4. Submit a Pull Request: Push changes and create a PR on GitHub.

---

Demo#

TODO#

Planned Academic Platforms#

• [√] arXiv
• [√] PubMed
• [√] bioRxiv
• [√] medRxiv
• [√] Google Scholar
• [√] IACR ePrint Archive
• [√] Semantic Scholar
• [√] Crossref
• [√] PubMed Central (PMC)
• [√] CORE
• [√] Europe PMC
• [√] Sci-Hub warning and enablement docs

Development Tasks#

• [√] Fix Async search bugs and ensure reliable fast MCP events
• [√] End-to-End full pipeline testing script (search, parse, download)
• [√] Establish two-layer federated architecture (Layer 1 tool: search_papers)
• [√] Ensure pervasive DOI extraction across metadata fields & abstract fallbacks
• Citation graph & Paper relation context feature
• [√] Expand full-stack OpenAlex provider

Priority Free and Open Sources#

• [√] PubMed Central (PMC)
• [√] CORE
• [√] OpenAlex
• [√] Europe PMC
• [√] OpenAIRE
• [√] dblp
• [√] CiteSeerX
• [√] DOAJ
• [√] BASE
• [√] Zenodo
• [√] HAL
• [√] SSRN (discovery + best-effort full-text)
• [√] Unpaywall (standalone DOI search source)

Optional and Non-Core Integrations#

• ResearchGate
• JSTOR
• ScienceDirect
• Springer Link
• [√] IEEE Xplore (optional skeleton — activate with IEEE_API_KEY)
• [√] ACM Digital Library (optional skeleton — activate with ACM_API_KEY)
• Web of Science
• Scopus

---

Star History#

---

License#

This project is licensed under the MIT License. See the LICENSE file for details.

---

Happy researching with paper-search-mcp! If you encounter issues, open a GitHub issue.