UniArticles MCP Server

English Version

总览

亿文通（UniArticles）是一个实现了模型上下文协议 (MCP) 的统一学术文献检索服务器。截至 v3.5.0，它把 9 个数据源、29 个工具——Scopus、ScienceDirect、arXiv、PubMed、Crossref、Europe PMC、DOAJ、OpenAIRE、CORE——统一到同一套标准化接口下，供 LLM 客户端（Codex Desktop、Cherry Studio、Claude Desktop 等）调用。

功能特性

• 统一接口: 所有数据源使用统一的返回结构。
• 多源支持: 支持9个不同领域的、包括OA与非OA的数据源查询。
• 标准化返回: 一致的 JSON 结构 (ok, source, query, count, items, error)。

当前支持的文献数据源

亿文通将以下 9 个数据源统一到同一套 MCP 接口下，全部返回相同的归一化 JSON 结构，且全部默认启用，共提供 29 个工具。除 arXiv 通过官方 arxiv Python 包封装外，其余每个数据源都是通过 httpx 直连该服务商的官方 REST API。

⚠️ API 密钥说明

本服务器提供的每一个工具、每一个数据源，都可以用您以个人身份申请的 API Key 访问，或者根本不需要 Key——没有任何一项需要机构订阅。 9 个数据源中有 5 个完全不需要 Key，需要 Key 的 4 个也都支持个人免费申请。

完全不需要 API Key 的数据源：arXiv、Crossref、Europe PMC、DOAJ、OpenAIRE。

注意：即使一个 Key 都不配置，服务器仍会注册并暴露全部 29 个工具——只有对需要 Key 的数据源的调用会失败，而且是以清晰的错误信息失败，不会从工具列表中悄悄消失。

安装与使用

方法一：直接集成到 LLM 客户端（推荐）

适用于 Cherry Studio、LM Studio、Claude Desktop、Trae 等。

本项目已发布至 PyPI，您无需下载完整项目源码，直接通过配置即可使用。 由于上述 LLM 客户端通常内置了 Python 和 uv 环境，您无需额外下载，只需在客户端的 MCP 配置文件（如 claude_desktop_config.json）中添加以下内容即可：

{
  "mcpServers": {
    "uniarticles-mcp-server": {
      "command": "uvx",
      "args": [
        "--refresh", 
        "uniarticles-mcp"
      ],
      "env": {
        "ELSEVIER_API_KEY": "your_elsevier_api_key_here",
        "NCBI_API_KEY": "your_ncbi_api_key_here",
        "CORE_API_KEY": "your_core_api_key_here"
      }
    }
  }
}

关于 env 字段：只有 ELSEVIER_API_KEY 是必需的（用于 Scopus / ScienceDirect），其余全部为可选项——如果您没有某个 Key，请整行删除（JSON 不支持注释，且删除后剩下的最后一行末尾不能带逗号）。各可选字段说明：

• ELSEVIER_API_KEY —— Elsevier相关的服务必须提供 Key 才可使用（在此申请）。

• NCBI_API_KEY —— PubMed 无此 Key 也能用；配置后仅将限速从 3 请求/秒提升到 10 请求/秒（在此申请）。

• CORE_API_KEY —— CORE 无此 Key 也能用，但额度低得多（未认证档 100 tokens/天、10 次/分钟，且不提供 fullText；配置后 1,000 tokens/天、25 次/分钟），使用 CORE 系工具时强烈建议配置（在此申请）。

如果您不希望每次重启时强制刷新缓存包，则改为添加以下内容：（但这会导致包更新时您需要对包进行手动更新）

{
  "mcpServers": {
    "uniarticles-mcp-server": {
      "command": "uvx",
      "args": [
        "uniarticles-mcp"
      ],
      "env": {
        "ELSEVIER_API_KEY": "your_elsevier_api_key_here",
        "NCBI_API_KEY": "your_ncbi_api_key_here",
        "CORE_API_KEY": "your_core_api_key_here"
      }
    }
  }
}

📖 如果您在该方法下遇见了任何问题，详见：傻瓜式配置攻略

如果您在启动服务时遇到 “MCP error -32000: Connection closed” 错误，请在 Cherry Studio 项目的该issue界面寻找解决方法：https://github.com/CherryHQ/cherry-studio/issues/3264

方法二：本地安装（高级）

需要 Python 3.10+ 和 uv (推荐) 或 pip。 此方法适合开发者或需要手动配置环境的用户。

使用 uv:

# 克隆仓库
git clone https://github.com/your-username/UniArticles_MCPserver.git
cd UniArticles_MCPserver

# 同步依赖并运行
uv sync
uv run uniarticles-mcp

使用 pip:

# 克隆并设置虚拟环境
python -m venv .venv
.venv\Scripts\activate

# 安装依赖
pip install -e .

# 运行
python -m uniarticles

配置说明

在项目根目录创建 .env 文件：

ELSEVIER_API_KEY=your_elsevier_api_key
# 必须配置。可以在 https://dev.elsevier.com/ 中申请。
NCBI_API_KEY=your_ncbi_api_key
# 可选。NCBI Entrez 无此 Key 也可用；配置后仅将 PubMed 限速从 3 请求/秒
# 提升到 10 请求/秒。免费申请：先登录 https://www.ncbi.nlm.nih.gov/
# 再前往 https://account.ncbi.nlm.nih.gov/settings/
# 可选。CORE 无此 Key 也可用，但额度低得多（未认证档 100 tokens/天、
# 10 次/分钟，且不提供 fullText；配置后 1,000 tokens/天、25 次/分钟）。
# 使用 CORE 系工具时强烈建议配置。免费申请：https://core.ac.uk/services/api#form
CORE_API_KEY=your_core_api_key

项目结构

src/
└── uniarticles/
    ├── server.py        # MCP Server 入口点
    └── sources/         # 数据源模块
        ├── arxiv.py
        ├── pubmed.py
        ├── scopus.py
        └── ...
pyproject.toml           # 项目元数据与依赖

验证安装

本项目未附带独立的测试套件；请通过启动服务来验证安装是否成功。服务通过 stdio 通信，启动成功后会保持运行并静默等待客户端发来的 JSON-RPC 输入（按 Ctrl+C 退出）：

uv run uniarticles-mcp     # 使用 uv 安装时
# 或
python -m uniarticles      # 使用 pip 安装时

若进程启动过程中没有出现导入或配置错误，即表示安装正常。

可用工具列表

以下工具按数据源分组，每个数据源一张表格。共注册 29 个工具，只要对应数据源的 Key（如有要求）已配置即可全部使用。每个工具都返回相同的归一化 JSON 结构（ok、source、query、count、items、error）。

Scopus

ScienceDirect

ArXiv

可用性提示：上游主机 export.arxiv.org 可能偶发卡住。在 2026-09-18 的全量回归中，arxiv_paper_detail_by_id 与 arxiv_latest_paper_list_by_category 均挂起约 5 分钟后以连接超时失败，而同一时刻、同一主机上的 arxiv_paper_search_by_query 在 1.4 秒内正常返回；约 15 分钟后故障自行恢复，三个工具全部正常。那次挂起原本是无上限的：arxiv.Client 根本不暴露任何超时参数，只有 page_size / delay_seconds / num_retries。自 v3.4.0 起，客户端改为单次请求 15 秒超时 + 整体 45 秒兜底，因此上游卡住时会快速失败并给出同时标明两个上限的可操作错误，而不是长时间挂起。_verify/arxiv_timeout_check.py 通过把客户端指向一个"只接受连接、从不响应"的本机监听来离线复现该行为；若真的遇到超时，可运行 _verify/arxiv_connectivity_test.py 做 DNS→TCP→TLS→HTTP 分层诊断，以区分上游卡顿与本机网络问题。

PubMed（NCBI Entrez）

以下工具直连 NCBI E-utilities。无 Key 即可使用；配置可选的 NCBI_API_KEY（NCBI 免费申请）仅将限速从 3 请求/秒提升到 10 请求/秒。

Crossref

Europe PMC

DOAJ

OpenAIRE

CORE

CORE 在本版本由 1 个工具扩展为 9 个（其余 8 个数据源共 20 个工具，合计 29）。它是本服务器唯一同时提供"分布统计"（年 / 出版社 / 学科等 facet）与"机构库画像"（某篇论文被哪些机构库采集）的数据源，其余 8 个源都只有"检索列表"或"按标识符取单条"。

work 与 output 的区别（选工具前先看这一句）：work 是 CORE 去重后的作品级记录（同一篇论文只有一条）；output 是未经去重的原始采集信号（同一篇论文在几个机构库被采集就有几条）。要论文本身用 works 系工具，要看某个采集副本的许可/仓库信息才用 outputs 系工具。

全部 CORE 工具均无条件注册（无 Key 也能调用，只是额度更低）。触发限流时错误信息会给出可重试时间与当前额度，并提示配置 CORE_API_KEY。

可参考agent提示词

你是一名文献检索助手，已接入 UniArticles 的 MCP 工具。
请严格按以下四步依次执行，不要跳步。

第一步 —— 检索之前，先拆分我的需求。
用一句话复述我到底要什么，并拆出以下要素：
（a）主题/研究问题；（b）检索类型：广泛扫描 / 定位某一篇已知文献 / 按作者或期刊查找；
（c）学科领域；（d）时间窗口；（e）语言；（f）需要多少篇算够用。

第二步 —— 判断哪些数据源「一定不匹配」，并明确告诉我。
按以下规则直接跳过，不要调用这些源：
- 主题仅属生物医学/生命科学 —— 排除 arXiv（学科不对口）。注意 DOAJ、CORE、
  OpenAIRE 是全学科的开放获取聚合源，生物医学一样覆盖，不要按学科排除它们；
  它们是否该排除只取决于下一条。
- 主题属物理、数学、计算机、统计、定量生物学、经济学 —— arXiv 可用；
  其他学科（人文社科、临床医学等）—— 排除 arXiv（它只有预印本，没有期刊覆盖）。
- 我要找同行评审 / 主流期刊 / 非开放获取的文献 —— 排除 DOAJ、CORE、OpenAIRE
  （三者只收开放获取内容，会把结果集带偏）。
- 我要全文或 PDF —— UniArticles 的任何工具都不返回全文或二进制文件。
  请先说明这一点，然后只把各源用作「元数据 + 链接」。
- 我要非英文（如中文）文献 —— 本服务器不收录 CNKI / 万方 / 维普，没有任何中文
  数据库源。实测「深度学习」这类中文查询：Crossref、DOAJ、CORE 能返回中文题录，
  Europe PMC 返回中文期刊的英译题录（标题带方括号），Scopus 命中不稳定（同一查询
  0~1 条），PubMed 与 arXiv 为 0 条。请如实说明覆盖率远低于中文数据库，不要声称
  可以替代 CNKI/万方。
- Scopus、ScienceDirect —— 仅在 `ELSEVIER_API_KEY` 已配置时可用。若调用返回授权/
  配额错误，把该源标记为「不可用」后继续，不要悄悄放弃这部分需求。
无论如何至少保留两个数据源。

第三步 —— 在剩下的数据源中按以下顺序检索，并遵循对应的查询写法。
1. Scopus —— 定位已知文献用 TITLE("完整标题")；主题检索用
   TITLE-ABS-KEY(词 AND 词)；count 取 5–10。
2. Crossref —— 普通关键词检索；同时用它核对每篇文献的 DOI。
3. PubMed（仅生物医学）—— 定位已知文献用  完整标题[Title]，且不要加引号，
   加了引号反而返回 0 条。不要直接传一长句自然语言：诸如 "in" 这类停用词
   会让整条查询归零。多个词组之间请显式使用 AND。
4. Europe PMC —— 字段语法与 PubMed 一致，例如 TITLE:"完整标题"。
5. arXiv（仅限预印本学科）—— 定位已知文献用 ti:"完整标题"；主题检索用 all:词。
6. DOAJ、CORE、OpenAIRE —— 仅开放获取。DOAJ 的相关度排序偏弱，
   用标题式查询会返回明显离题的结果，因此每一条都必须先核对标题再写进结果。
   CORE 除了检索，还能给出**分布统计**（core_work_aggregate_by_query，比如这批
   文献都发在哪些年/出版社）与**机构库画像**（core_data_provider_* / 
   core_work_outputs_by_id，比如某篇论文被哪些机构库采集）；需要这类信息时
   直接调用对应工具，不要用其它源的结果自行拼凑。
7. ScienceDirect —— 只能按标识符查询（DOI/PII），它没有检索工具，不要试图检索。
每个源取 5–10 条。同一主题在多个源各查一遍是预期用法，而不是「失败后降级」。
任何源报错就跳过，并记录下来。

第四步 —— 汇总成表并汇报。
先按 DOI 去重，再按归一化标题去重。只输出一张 Markdown 表格，按发表时间由新到旧：

| 文献标题 | 标题翻译 | 发表时间 | 期刊/会议 | DOI 链接 | 文献源 | 内容介绍 |

- 标题翻译：把文献标题翻译成中文；若原标题已是中文，此列填「—」。
- DOI 链接：[10.xxxx/yyy](https://doi.org/10.xxxx/yyy) 格式；若无 DOI，则给出该源的原始链接。
- 内容介绍：1–2 句，且只能依据工具真实返回的摘要撰写。
  没有摘要时写「无摘要」，严禁自行编造或推测内容。
- 文献源：填工具返回的 `source` 值；同一篇文献被多个源命中时全部列出。
表格之后，再列出：跳过了哪些源及原因，以及哪些查询返回了 0 条结果。

我的需求：<在这里写下你要查找的内容>

🤝 贡献与共建

囿于笔者主修化学方向，对其他研究方向的数据库及API开发情况不甚了解，欢迎有志之士提出PR、贡献其他数据源。

⚖️ 协议与致谢

协议

双许可：AGPL-3.0-or-later 或 商业授权

本项目以 GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL-3.0-or-later） 开源发布，全文见 LICENSE。你可以据此自由使用、修改与再分发，包括商业用途——前提是遵守 AGPL 条款：若你分发修改后的版本，或将其作为网络服务提供给用户，必须向这些用户提供对应的源代码。

💼 商业授权： 若 AGPL 的传染性条款不适合你的场景——例如需要闭源集成到商业产品中，或需要在不公开修改的前提下将修改版作为网络服务运营——可另行联系作者获取商业授权：wangzh685@mail2.sysu.edu.cn。

说明：此前“AGPL-3.0 with commercial restriction（商业使用受限）”的表述不准确，已在 v3.4.0 更正。AGPL 并不限制商业使用，它限制的是闭源再分发与闭源网络服务。

特别致谢

• ScopusMCP: ScopusMCP是笔者第一个开发成功的文献检索MCP工具，但初始相当臃肿与难以移植，感谢舍友 (https://github.com/qwe4559999) 提供的使用pypi和uv打包的建议。

特别声明

本项目使用了人工智能生成内容。