Paper Search Mcp

Paper Search MCP

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

---

目录

• 概览
• 项目原则
• MCP 授权兼容性
• 功能
• 来源策略
• Sci-Hub 声明
• 安装
  • Claude Code（Skill）
  • 方法 1 — Smithery
  • 方法 2 — uvx
  • 方法 3 — uv
  • 方法 4 — pip
  • 方法 5 — npx
  • 方法 6 — Docker
  • 方法 7 — 克隆并从源代码运行
  • DeepSeek Harness（DSH）
  • 环境变量
• 贡献
• 演示
• Star 历史
• 许可证
• 待办事项

---

概览

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

项目原则

• 免费优先：公共和开放数据源是默认的发展方向。付费或受限来源并非本项目的核心方向。
• 可选 API 密钥：仅当 API 密钥能够提升稳定性、速率限制或元数据质量时才支持使用。只要可能，不使用 API 密钥也应能使用 MCP。
• 便于大模型检索：搜索结果应标准化、去重，并尽可能完整，以支持下游大模型工作流。
• 来源透明：不同来源各有优势。MCP 应明确说明这些取舍，而不是声称每个来源都支持全文检索。

---

MCP 授权兼容性

随附的 MCP 服务支持 stdio（默认）、sse 和 streamable-http。网络传输默认绑定到 127.0.0.1。可选的 OAuth 受保护资源模式会借助外部授权服务，为这两种 HTTP 传输添加标准发现、JWT bearer token 验证和必需的作用域。

使用 --auth oauth 或 PAPER_SEARCH_MCP_AUTH=oauth 启用此模式，并按照OAuth 受保护资源设置中的说明进行明确的 issuer/JWKS/resource/audience/scope 配置。HTTP 身份验证设置无效或不完整时，服务将无法启动。stdio 不受 HTTP 身份验证影响。未配置 OAuth 的本地 HTTP 保持开放；请勿直接公开该监听器。受保护的远程部署仍需要 TLS、速率限制和文件系统隔离。此功能不提供登录/账户功能，也不会取代外部 issuer 的 OAuth 流程；部署前必须验证其与实时身份提供方的互操作性。

---

功能

• 两层架构：
  • 第 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、OpenReview、Unpaywall（DOI 查询）以及可选 Sci-Hub 工作流的论文。
• 可选快速搜索：CLI 搜索默认保持广泛覆盖。更看重低延迟而非覆盖面时，可使用 -s fast（OpenAlex、Crossref、arXiv、PubMed、Europe PMC）或 -s fastest（OpenAlex 和 Crossref）。
• 标准化输出：通过 Paper 类以一致的字典格式返回论文。
• 优先免费设计：在使用任何可选商业或受限集成之前，优先选择开放和公共来源。
• 可选 API 密钥增强：Semantic Scholar 等来源在用户提供 API 密钥时效果可能更好，但不会强制使用付费服务。
• 发现与检索工作流：Google Scholar 和 Crossref 可用于发现论文并补充 DOI；在条件允许时，则使用开放仓库和出版商链接，以合法方式获取全文。
• 优先开放获取的回退链：download_with_fallback 现在按顺序尝试来源原生下载 → OpenAIRE/CORE/Europe PMC/PMC 发现 → Unpaywall DOI 解析 → 可选 Sci-Hub。
• 有界引用查询：通过 DOI 或 OpenAlex ID 查询 OpenAlex 参考文献和引用论文，并提供明确的预算和截断元数据。
• MCP 集成：兼容 MCP 客户端，可增强大模型上下文。
• DeepSeek Harness (DSH) 集成：提供一个 dsh 配置包（克隆仓库，运行 npx @deepseek-ai/[email protected] plugin --profile web add link:./dsh），将每个工具公开为 mcp__paper-search__*，并可选提供指导技能。
• 可扩展设计：通过扩展 academic_platforms 模块，轻松添加新的学术平台。

来源策略

长期目标不是依赖单一搜索引擎，而是结合多个免费和公共来源，并明确各自的作用：

• 开放元数据基础：Crossref、OpenAlex、Semantic Scholar、dblp、CiteSeerX、SSRN、Unpaywall（以 DOI 为核心的开放获取元数据）。
• 学科专用来源：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 用作发现回退来源，而非主要权威来源。

平台能力矩阵

此矩阵反映了本仓库功能测试和端到端回归测试中经验证的实时集成结果。各列显示正常情况下观察到的最高能力级别。

平台	搜索	下载	阅读	备注
arXiv	✅	✅	✅	开放 API；可靠
PubMed	✅	❌	⚠️ 仅信息	开放 API；可靠
bioRxiv	✅	✅	✅	开放 API；可靠
medRxiv	✅	✅	✅	开放 API；可靠
Google Scholar	⚠️	❌	❌	上游机器人检测／速率限制可能导致无法搜索；报告为来源错误
IACR	✅	✅	✅	开放 API；可靠
Semantic Scholar	✅	✅（OA）	✅（OA）	无需密钥即可使用（有速率限制）；密钥可提高限制；密钥被拒绝（403）时会自动重试且不使用密钥
Crossref	✅	❌	⚠️ 仅信息	开放 API；可靠
OpenAlex	✅	❌	⚠️ 仅信息	开放 API；免费 API 密钥可提高每日限制
PMC	✅	✅（仅 OA）	✅（仅 OA）	仅限 OA PDF；某些代理环境可能会阻止直接下载
CORE	✅	✅（取决于记录）	✅（取决于记录）	建议使用免费密钥；连接器会退避重试，并在 401/403 时改为不使用密钥
Europe PMC	✅	✅（OA）	✅（OA）	仅限 OA PDF；某些代理环境可能会阻止直接下载
dblp	✅	❌	⚠️ 仅信息	开放 API；可靠
OpenAIRE	✅	❌	❌	开放 API；在遇到暂时性 403 时，会使用逐步调整的请求配置重试 3 次
CiteSeerX	⚠️	✅（取决于记录）	⚠️	API 端点间歇性不可用／重定向至网络存档
DOAJ	✅	⚠️（取决于 URL）	⚠️（取决于 URL）	PDF 是否可用因文章而异；免费密钥可提高速率限制
BASE	⚠️	✅（取决于记录）	✅（取决于记录）	OAI-PMH 端点需要注册机构 IP；否则会正常返回空结果
Zenodo	✅	✅（取决于记录）	✅（取决于记录）	开放 API；可靠
HAL	✅	✅（取决于记录）	✅（取决于记录）	开放 API；可靠
SSRN	✅（OpenAlex 元数据）	⚠️ 尽力提供	⚠️ 尽力提供	已验证公开发现功能；SSRN 页面／PDF 的身份必须另行验证
OpenReview	✅（匿名 API v2）	⚠️ 仅公开内容	⚠️ 仅公开内容	已验证搜索功能；实时 PDF 检查中的精确 note 查询返回 403；PDF 成功仅通过模拟测试验证
Unpaywall	✅（DOI 查询）	❌	❌	需要 PAPER_SEARCH_MCP_UNPAYWALL_EMAIL
Sci-Hub（可选）	⚠️ 仅回退	✅	❌	可选；镜像站不稳定；由用户自行负责
IEEE Xplore 🔑	⚠️ 已配置元数据	❌	❌	仅进行了确定性测试；未进行通过密钥认证的实时验证；元数据密钥不授予全文访问权限
ACM DL	✅（Crossref 元数据）	⚠️	⚠️	无密钥搜索；浏览器验证可能会阻止直接 PDF 下载／阅读；请使用 OA 回退方案

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

---

凭据和 API 密钥要求

除非另有说明，所有密钥均为可选。请在 ~/.config/paper-search-mcp/.env（推荐）中配置，或通过 shell 导出。

环境变量	提供方	是否必需？	获取方式
PAPER_SEARCH_MCP_UNPAYWALL_EMAIL	Unpaywall	是（未配置时会停用 Unpaywall）	任意有效邮箱；在 unpaywall.org 注册
PAPER_SEARCH_MCP_CORE_API_KEY	CORE	推荐	在 core.ac.uk/services/api 免费获取
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar	可选	在 semanticscholar.org 免费获取——可提高速率限制
PAPER_SEARCH_MCP_OPENALEX_API_KEY	OpenAlex	可选	在 openalex.org/settings/api 免费获取；可将无密钥时的每日限额提高 10 倍
PAPER_SEARCH_MCP_OPENALEX_EMAIL	OpenAlex	可选	用于 OpenAlex User-Agent 的联系邮箱
PAPER_SEARCH_MCP_GOOGLE_SCHOLAR_PROXY_URL	Google Scholar	可选	你的 HTTP/HTTPS 代理 URL；无法保证访问，也不会解除提供方限制
PAPER_SEARCH_MCP_DOAJ_API_KEY	DOAJ	可选	在 doaj.org 免费获取——可提高每小时速率限制
PAPER_SEARCH_MCP_ZENODO_ACCESS_TOKEN	Zenodo	可选	在 zenodo.org 免费获取——访问私有记录时必需
PAPER_SEARCH_MCP_IEEE_API_KEY	IEEE Xplore	激活所必需	在 developer.ieee.org 免费获取

所有变量均采用 PAPER_SEARCH_MCP_<NAME> 前缀格式。为保持向后兼容，仍支持不带前缀的旧名称（例如 CORE_API_KEY、UNPAYWALL_EMAIL）。

---

已知上游限制

某些搜索失败是由外部提供方不稳定导致的，并非本项目中的错误：

来源	症状	原因	解决方法
Google Scholar	HTTP/网络故障、CAPTCHA 或持续显示同意页面时出现来源错误	上游速率限制、访问检查或连接问题	降低请求频率或使用其他公共来源；不会自动解决 CAPTCHA
Semantic Scholar	429 速率限制响应	匿名访问速率限制	设置 PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY；如果密钥被拒绝（403），连接器会自动在不使用密钥的情况下重试
OpenAlex	403/429 或每日配额错误	匿名访问每日限制	设置 PAPER_SEARCH_MCP_OPENALEX_API_KEY
CORE	500 / 超时错误	未认证访问的速率限制	设置 PAPER_SEARCH_MCP_CORE_API_KEY（免费）；连接器会采用指数退避重试，并在 401/403 时回退为不使用密钥
OpenAIRE	间歇性 403 响应	基于 IP 的会话速率限制	连接器会针对每个配置重试 3 次，逐步尝试：普通会话 → XML Accept 标头 → 使用 Mozilla UA 的原始 requests.get
CiteSeerX	通过网页存档重定向时出现 404	PSU 端点间歇性重定向到存档	无解决方法；连接器会正常返回空结果
BASE	搜索返回 0 条结果	OAI-PMH 端点要求使用机构 IP 注册	在 base-search.net 注册以获取 API 访问权限；否则连接器会正常返回空结果
SSRN 全文	HTTP 403 或无法获取身份信息	可能限制公共页面/PDF 的分发	搜索使用 OpenAlex；未登录时，下载会报告失败，不会尝试重定向或回退到 HTML 搜索
PMC / Europe PMC	PDF 下载出现 ProxyError	本地代理阻止直接通过 HTTPS 下载 PDF	禁用代理或改用 download_with_fallback

在统一 MCP 和 CLI 搜索中，Google Scholar 的失败会通过 errors.google_scholar 显示，而成功的来源仍会返回其论文。直接进行 Scholar 搜索时，这些失败会引发 GoogleScholarSearchError。正常的空结果页面仍会返回空列表。如果后续页面失败，该来源会被报告为失败，而不会将先前页面作为完整结果返回。超时也会引发来源错误，而不是表示不存在论文。在 HTTP 403/429/503 重试耗尽或遇到 CAPTCHA 后，共享的 Scholar 连接器会进入 60 秒冷却期。连续遇到访问阻止会以指数方式延长冷却期，最长可达 15 分钟；有效的上游 Retry-After 也可以延长此时间间隔。成功获取页面后，连续失败计数会重置。冷却期间的调用会立即失败并返回重试间隔，且不会联系 Scholar。重试会遵循有效的 Retry-After 秒数或 HTTP 日期，最长不超过 24 小时。如果上游要求等待更久，连接器会在其生命周期内暂停自动请求，而不会早于提供方要求的时间重试。超过 30 秒的延迟会延续到后续调用，工作线程不会因此休眠。并发调用会共享同一个限速会话。连接器不会在请求之间轮换身份，也不会解决 CAPTCHA。冷却状态仅限于进程内，不代表上游配额，也不保证该时间间隔过后服务会恢复。

进行综述时，请明确选择替代来源，例如 MCP search_papers(query, sources="google_scholar,openalex,semantic,crossref") 或 CLI paper-search search "query" -s google_scholar,openalex,semantic,crossref。即使 Scholar 处于冷却期，成功的提供方也会保留各自的来源标签及其论文。替代来源有各自的访问/速率限制；它们绝不会被悄然作为 Google Scholar 结果返回。

本地 PDF 章节提取

extract_sections 会在已下载的 PDF 中，按可识别的独立标题进行拆分，并在明确的限制和截断规则下，保留提取文本的顺序和页码范围。读取仅限于配置的下载根目录；不会联网、进行 OCR 或医学推断，也不会新增依赖。章节标签基于启发式规则，可能存在不确定性。有关访问规则、CLI 用法和解析器限制，请参阅有界 PDF 章节。

arXiv PDF 下载和读取

arXiv 下载会验证现代或旧版格式的纯论文 ID，串行处理并控制请求频率，检查 HTTP 状态，将最多 100 MiB 的内容流式传输到同一目录下的临时文件，并在原子替换目标文件之前检查 PDF 文件头和解析器。传输失败或 PDF 无效时，现有文件不会更改。下载使用 10 秒连接超时和 30 秒读取超时，但不限制传输或解析器运行的总时长，也不会自动重试被拒绝的响应。read arxiv 会将无效、加密或仅含图像的 PDF 报告为错误，而非返回成功但内容为空的结果；它不会执行 OCR，也不会删除无效的缓存文件。

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

IEEE Xplore 提供可选择启用的元数据搜索，只有配置现有 API 密钥后才会启用。 ACM Digital Library 搜索无需密钥，默认启用，使用 Crossref 元数据，并限定为 ACM DOI 前缀 10.1145。

平台	环境变量	状态
IEEE Xplore	PAPER_SEARCH_MCP_IEEE_API_KEY	支持分页的元数据搜索；暂不支持直接下载和读取
ACM Digital Library	无	由 Crossref 提供支持的搜索；PDF 下载和读取取决于出版商的访问权限

启用方法：

export PAPER_SEARCH_MCP_IEEE_API_KEY=<your_ieee_key>       # free key at https://developer.ieee.org/

配置 IEEE 密钥后，启动时会注册 ieee 及其工具。请参阅 IEEE 元数据限制和全文边界。ACM（acm、search_acm、download_acm 和 read_acm_paper）始终可用。旧版 PAPER_SEARCH_MCP_ACM_API_KEY / ACM_API_KEY 设置已不再使用，可以移除。

ACM 下载需要 ACM DOI，例如 10.1145/...。出版商的浏览器验证可能会阻止脚本访问；可使用 download_with_fallback(source="acm", paper_id="10.1145/...", doi="10.1145/...") 尝试开放仓库。read_acm_paper 会先将 PDF 下载到 save_path，再提取文本，并且可能覆盖该文件。

扩展免费来源（第 4 阶段）

其他公共来源连接器已集成到 MCP 服务中：

• zenodo：Zenodo 官方 REST API 连接器（搜索，以及视记录而定的 PDF 下载和读取支持）。
• hal：HAL 公共 API 连接器（搜索，以及视记录而定的 PDF 下载和读取支持）。
• ssrn：基于 OpenAlex 的发现功能，严格核验 SSRN 身份，并尽力验证公开下载链接。
• openreview：匿名公开 API v2 论文，不包括评审和私人笔记；支持下载和读取经验证由 OpenReview 托管的 PDF。
• unpaywall：以 DOI 为中心的 OA 元数据来源，可用于独立查询（search_unpaywall）和回退 URL 解析。

SSRN 集成始终以合规为先：它只会尝试 SSRN 页面公开提供的 PDF 直链。如果需要登录或受限访问，连接器会返回明确提示，而不会绕过访问控制。

Sci-Hub 声明

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

• download_with_fallback 默认不启用 Sci-Hub。只有在明确选择使用时才传入 use_scihub=true。
• 可用性不稳定，镜像站也经常变更。
• 法律和政策风险因司法管辖区而异。
• README 和工具说明应明确指出，启用和使用该功能的责任由用户承担。
• 应尽可能优先尝试开放获取来源和出版商许可的来源。

---

安装

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

---

Claude Code（技能）——推荐 Claude Code 用户使用

将其安装为 Claude Code 技能，而不是 MCP 服务。这样，当你提到查找论文、学术文献等内容时，Claude 就能自动搜索论文，无需配置 MCP。

前提条件：uv 和 Claude Code。

步骤 1 — 安装 CLI：

uv tool install paper-search-mcp

步骤 2 — 安装技能：

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

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

创建 ~/.config/paper-search-mcp/.env，用于配置可选 API 密钥（请参阅环境变量）。

就是这样。 下次启动 Claude Code 时，只需让它查找论文，技能就会自动启用。例如：

• “帮我查找近期关于 CRISPR 碱基编辑的论文”
• “在 arxiv 和 semantic scholar 上搜索关于 transformer 注意力机制的资料”
• “下载 arxiv 论文 2106.12345 的 PDF”

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

只有当返回路径指向可读取、非空且具有 PDF 文件头的常规文件时，paper-search download 才会报告 status: "ok"。连接器错误字符串、缺失文件以及保存的 HTML 错误页面都会生成 JSON 错误，并以退出代码 1 退出。这项轻量检查不能确认 PDF 完整性或论文身份；这些检查仍由源连接器和阅读器负责。

需要控制延迟时，请显式选择来源：

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

CLI 默认仍使用 -s all 这一广泛来源集合。--exhaustive 是受支持的兼容性空操作，因为广泛搜索本来就是默认设置。显式的 -s 选择始终优先，包括 -s fast 和 -s fastest。广泛预设包含所有受支持的公开来源；可选的付费来源不会加入这些预设。

-s fast 会选择 OpenAlex、Crossref、arXiv、PubMed 和 Europe PMC。非空白的 PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY（或旧版 SEMANTIC_SCHOLAR_API_KEY）也会加入 Semantic Scholar。-s fastest 只选择 OpenAlex 和 Crossref。这些预设以降低延迟为导向，并不保证响应时间或全面覆盖文献。匿名 Semantic Scholar 请求收到 429 响应时会立即失败；经过身份验证的请求仍会进行有限次数的重试。

只会构建选中的搜索器。来源列表和预设会严格遵循：查询中的 DOI 不会增加其他来源。查询 DOI 时请使用 -s unpaywall，或者在逗号分隔的来源列表中显式加入 unpaywall。广泛的 all 预设已包含它。MCP 服务的搜索默认设置保持不变。

若要避免响应缓慢的来源拖延 CLI 搜索，可选择为每个来源设置截止时间：

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

--source-timeout SECONDS 必须是正的有限数值。它会在独立的 Python 进程中运行所选来源，最多同时运行 4 个。每个来源的计时从操作系统进程创建完成后开始，涵盖 Python／提供方初始化、搜索、序列化和工作进程退出。进程创建、等待工作进程空位以及进程清理所花的时间会增加额外开销，不计入此计时。这不是整个命令的截止时间。超时的工作进程会被终止并回收，然后才会重用其空位，因此受阻的网络调用不会拖延 Python 线程执行器的关闭。成功来源会保留其结果；超时来源会列入 errors，其 source_results 计数为 0。来源选择、标签、排序、JSON 字段以及部分结果的退出状态（0）均保持不变。子进程启动会增加开销，尤其是在预算非常短时。不加此标志时，现有的连接器专属超时设置和进程内搜索行为保持不变。

按引用次数或发表日期对搜索结果排序：

paper-search search "transformer attention" --sources arxiv,semantic --sort citations
paper-search search "CRISPR" --sort date

--sort relevance（默认值）会保留现有顺序：先按来源的选择顺序排列，再保持每个来源返回的原始顺序。它不会计算跨来源的相关性分数。--sort citations 会按引用次数从高到低排序；--sort date 会按出版日期从新到旧排序。排序在去重后于客户端进行，且仅涵盖检索到的结果（--max-results 按来源计算）；它不会更改来源查询，也不会搜索整个来源集合来查找引用次数最多或最新的论文。并列项保留原始顺序。缺失或无效的值排在最后；支持数字格式的引用次数。日期接受 ISO 日期和时间戳，其中无时区的时间戳和仅含日期的值均视为 UTC。默认 JSON 输出和已选来源保持不变。

CLI 中的 MCP 工具

paper-search tool 会调用与 MCP 服务相同的已注册工具，包括特定来源的选项和 DOI 查询。必需参数使用位置参数；可选参数使用 kebab-case 标志。布尔标志使用 --flag 和 --no-flag；省略选项时保留其 MCP 默认值。

paper-search tool --help
paper-search tool --list  # JSON tool list, schemas, and annotations
paper-search tool search_crossref --help
paper-search tool search_crossref "transformer attention" --filter from-pub-date:2024-01-01 --sort published --order desc --max-results 2
paper-search tool get_crossref_paper_by_doi 10.1038/nature12373
paper-search tool search_iacr "cryptography" --no-fetch-details

对象和列表以 JSON 返回；文本和下载路径以纯文本返回。发生异常时会返回 JSON 错误，退出代码为 1；CLI 语法无效时退出代码为 2。普通 MCP 结果会保留其原始含义，包括工具自身返回的错误或部分结果字段。--list 仅显示当前配置启用的工具，因此 IEEE 工具仍需要 API 密钥。现有的 search、download、read 和 sources 命令保持不变。工具调用会沿用 MCP 工具的来源选择和超时行为；Sci-Hub 回退仍需通过 --use-scihub 显式启用。

技能 ZIP 上传和其他 Claude 运行环境

上述步骤会按照 Claude Code 技能目录结构，在 ~/.claude/skills/paper-search/SKILL.md 安装一个本地 Claude Code 技能。这些步骤不需要上传 ZIP。

GitHub 的Download ZIP包含整个代码仓库，技能位于 paper-search-mcp-main/claude-code/ 下。它不是独立的技能压缩包。如果上传器提示 SKILL.md 嵌套层级过深，请先检查压缩包的目录结构。Anthropic 的自定义技能打包指南规定，压缩包根目录下应有一个技能文件夹，技能文件应直接放在该文件夹内：

paper-search-skill.zip
└── paper-search/
    └── SKILL.md

要创建此目录结构以供检查或调整，请在代码仓库检出目录中运行以下命令（需要 Python 3；会覆盖 paper-search-skill.zip）：

from zipfile import ZIP_DEFLATED, ZipFile

with ZipFile("paper-search-skill.zip", "w", compression=ZIP_DEFLATED) as archive:
    archive.write("claude-code/SKILL.md", arcname="paper-search/SKILL.md")

也可使用可复用的构建脚本：python scripts/build_skill_zip.py --output paper-search-skill.zip。除非提供 --force，否则脚本不会覆盖现有文件。其压缩包目录结构、前置元数据和逐字节一致的指令内容均由离线测试覆盖。

这只会打包指令；不会捆绑 Python 依赖、安装 paper-search，也不会配置 MCP 连接。打包的技能要求运行环境能够执行 CLI 并访问学术服务。本项目尚未验证 Claude 网页版或其他运行环境是否接受上传或能否执行。调整技能前，请查看相应运行环境当前对元数据、软件包安装、网络访问和代码执行的要求。如果想改用 MCP 客户端，请按照下文的 MCP 安装方法操作；上传技能 ZIP 不会启动或连接外部 MCP 服务。

---

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

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

---

方法 1 — Smithery（单命令安装，推荐用于 Claude Desktop）

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

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

---

方法 2 — 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 Desktop 配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uvx",
      "args": ["paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "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": ""
      }
    }
  }
}

---

方法 3 — uv（持久安装）

uv tool install paper-search-mcp

Claude Desktop 配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "uv",
      "args": ["tool", "run", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "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": ""
      }
    }
  }
}

---

方法 4 — pip（标准 Python 安装）

pip install paper-search-mcp

Claude Desktop 配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "python",
      "args": ["-m", "paper_search_mcp.server"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "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": ""
      }
    }
  }
}

如果 python 不在 PATH 中，请将其替换为完整路径（例如 /usr/bin/python3 或 C:\Python311\python.exe）。运行 which python3 / where python 查找其路径。

---

方法 5 — npx（通过 Smithery CLI，无需本地 Python）

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

Claude Desktop 配置：

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

---

方法 6 — Docker

docker build -t paper-search-mcp .
docker run --rm -i \
  -e [email protected] \
  -e PAPER_SEARCH_MCP_CORE_API_KEY=your_core_key \
  paper-search-mcp

Claude Desktop 配置：

{
  "mcpServers": {
    "paper-search-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_MCP_UNPAYWALL_EMAIL": "[email protected]",
        "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": ""
      }
    }
  }
}

---

方法 7 — 克隆并从源代码运行（开发 / 推荐用于 macOS 本地运行）

这是在 macOS 上最可靠的方法——无需包装脚本，也不会遇到 realpath 问题。

# 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 配置（将目录路径替换为实际的克隆位置）：

{
  "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": "[email protected]",
        "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": ""
      }
    }
  }
}

例如，如果你克隆到了 /Users/mac/Pengsong/paper-search-mcp：

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

uv run 会在首次运行时自动将依赖项安装到隔离环境中——无需运行 pip install，也无需创建 venv。

如果要运行一个共享网络服务，而不是为每个客户端启动一个 stdio 进程：

paper-search-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

可用的传输方式包括 stdio、sse 和 streamable-http。默认方式仍为 stdio。也可以通过 PAPER_SEARCH_MCP_TRANSPORT、PAPER_SEARCH_MCP_HOST、 PAPER_SEARCH_MCP_PORT 和 PAPER_SEARCH_MCP_PATH 设置相同的网络参数；命令行选项 优先级更高。使用默认的 --auth none 时，绑定到 0.0.0.0 等非环回主机 会暴露一个未经身份验证的服务。对于受保护的 HTTP，请配置 可选的 OAuth 模式，并确保后端位于 TLS 和适当的部署控制措施之后；否则，请使用经过身份验证的网关。

在主动开发期间，可以选择安装一个可编辑副本：

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

---

DeepSeek Harness（DSH）

可在 DeepSeek Harness（dsh）中通过配置包使用论文搜索：它会启动 MCP 服务，并在任何 dsh 配置中将其所有工具注册为 mcp__paper-search__*。该配置包只会挂载一行组合配置，不会改动 MCP 服务本身。

前提条件：uv（默认启动器为 uvx）和 pnpm（dsh plugin 会转发给 pnpm）。以下命令使用 npx @deepseek-ai/dsh 启动器（无需全局安装）；如果已全局安装 dsh，请去掉此前缀。

git clone https://github.com/openags/paper-search-mcp.git
cd paper-search-mcp
npx @deepseek-ai/[email protected] plugin --profile web add link:./dsh

link: 会根据检出内容更新配置包配置。git pull 不会更新单独启动的 PyPI 服务；有关从源代码检出目录启动以及可复现的版本选择，请参阅 dsh/README.md。将 web 替换为你的配置名称；如果配置不存在，系统会自动初始化。重启配置（运行 npx @deepseek-ai/[email protected] web 或重新启动）后，工具就会出现，例如 mcp__paper-search__search_papers、mcp__paper-search__download_with_fallback、mcp__paper-search__search_arxiv。

API 密钥：只需按照环境变量中的说明操作——服务会自动加载 ~/.config/paper-search-mcp/.env。DSH 会有意清除子进程中的凭据类环境变量，因此 shell 导出的变量不会传递给服务；如需显式传递变量，请在 ~/.dsh/profiles/<name>/cordis.patch.yml 中覆盖 mcp-paper-search 行（配置覆盖会替换整个对象——完整示例请参阅 dsh/README.md）。

可选技能，包含用法指引（工作流、来源表、工具映射）：

mkdir -p ~/.dsh/skills && cp -r dsh/skills/paper-search ~/.dsh/skills/

卸载：

npx @deepseek-ai/[email protected] plugin --profile web remove paper-search-mcp-dsh
rm -rf ~/.dsh/skills/paper-search

移除配置包后，系统会从组合配置中移除对应行。此操作不会删除已下载的论文、软件包缓存或用户管理的设置。

如果你已通过自己的 @deepseek-ai/dsh-mcp-client 行运行 paper-search-mcp，请先移除该行（或为其中一个指定不同的 serverName），再添加配置包——重复的 serverName 会导致加载失败。配置包的软件包版本与此检出目录的 Python 项目版本一致；dsh/README.md 介绍了其他启动方式（uv tool run、python -m、npx）、环境变量传递和开发说明。

---

环境变量（.env 文件）

除了将密钥直接写入 JSON 配置，你也可以将其存储在用户配置文件中（启动时自动加载）：

mkdir -p ~/.config/paper-search-mcp
curl -fsSL https://raw.githubusercontent.com/openags/paper-search-mcp/main/.env.example \
  -o ~/.config/paper-search-mcp/.env
$EDITOR ~/.config/paper-search-mcp/.env

[email protected]
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=

如需使用自定义路径：export PAPER_SEARCH_MCP_ENV_FILE=/absolute/path/to/.env

为保持向后兼容，仍支持不带 PAPER_SEARCH_MCP_ 前缀的旧变量名（例如 CORE_API_KEY、UNPAYWALL_EMAIL）。

---

可选的本地搜索缓存

启用 SQLite 搜索缓存后可添加 TTL、大小限制、状态查看和清除功能。该功能默认禁用，且不会缓存需要身份验证的来源。

贡献

欢迎贡献！以下是开始参与的方法：

1. Fork 仓库： 在 GitHub 上点击“Fork”。

2. 克隆并设置：

   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. 进行更改：

   • 在 academic_platforms/ 中添加新平台。
   • 在 tests/ 中更新测试。

4. 提交 Pull Request： 推送更改，并在 GitHub 上创建 PR。

---

演示

待办事项

计划支持的学术平台

• [√] arXiv
• [√] PubMed
• [√] bioRxiv
• [√] medRxiv
• [√] Google Scholar
• [√] IACR ePrint Archive
• [√] Semantic Scholar
• [√] Crossref
• [√] PubMed Central (PMC)
• [√] CORE
• [√] Europe PMC
• [√] Sci-Hub 警告和启用文档

开发任务

• [√] 修复异步搜索问题，确保 MCP 事件快速且可靠
• [√] 端到端完整流水线测试脚本（搜索、解析、下载）
• [√] 建立双层联邦架构（第 1 层工具：search_papers）
• [√] 确保从元数据字段和摘要回退内容中全面提取 DOI
• 引用图谱与论文关系上下文功能
• [√] 扩展完整技术栈的 OpenAlex 提供方

优先支持的免费和开放来源

• [√] PubMed Central（PMC）
• [√] CORE
• [√] OpenAlex
• [√] Europe PMC
• [√] OpenAIRE
• [√] dblp
• [√] CiteSeerX
• [√] DOAJ
• [√] BASE
• [√] Zenodo
• [√] HAL
• [√] SSRN（发现 + 尽力获取全文）
• [√] Unpaywall（独立 DOI 搜索来源）

可选的非核心集成

• ResearchGate
• JSTOR
• ScienceDirect
• Springer Link
• [√] IEEE Xplore（可选骨架 — 使用 IEEE_API_KEY 激活）
• [√] ACM Digital Library（无需密钥的 Crossref 搜索；出版商 PDF 的访问情况不一）
• Web of Science
• Scopus

---

Star 历史

---

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

---

祝你使用 paper-search-mcp 研究愉快！如果遇到问题，请提交 GitHub issue。

显式机构元数据连接器

Web of Science Starter 只能通过 search_wos 或显式指定 wos 来源使用（paper-search search 'TI=(machine learning)' -s wos）。提供密钥不会将其加入默认、all、fast 或 fastest 搜索。运行时请提供 PAPER_SEARCH_MCP_WOS_API_KEY（也支持旧版 WOS_API_KEY）；此连接器不会创建账户或持久保存凭据。有关限制、错误、能力边界和验证状态，请参阅机构连接器指南。

Scopus 同样仅支持显式调用（-s scopus 或 MCP search_scopus），使用 PAPER_SEARCH_MCP_SCOPUS_API_KEY（旧版 SCOPUS_API_KEY 也可用）。元数据搜索默认使用 STANDARD。可通过 paper-search read scopus ID 或 MCP read_scopus_paper 获取摘要。检索 ScienceDirect 文章则需要显式设置 --full-text / full_text=true，并验证 DOI/PII 匹配。响应会分别标记 full_text、abstract_only 和 unavailable。这些基于测试样例的测试并未验证任一连接器的实时机构访问权限。