🚀 Unpaywall MCP 服务器
Unpaywall MCP 服务器通过 MCP（模型上下文协议）暴露 Unpaywall 工具，使 AI 客户端能够：
- 通过 DOI 获取元数据
- 搜索文章标题
- 获取最佳的开放获取全文链接
- 下载开放获取的 PDF 并提取文本
🚀 快速开始
使用 npx 快速启动
将以下内容添加到你的 MCP 客户端配置中（以 Claude Desktop 为例）：
{
"mcpServers": {
"unpaywall": {
"command": "npx",
"args": ["-y", "unpaywall-mcp"],
"env": { "UNPAYWALL_EMAIL": "you@example.com" }
}
}
}
然后尝试使用这些工具：unpaywall_search_titles、unpaywall_get_fulltext_links、unpaywall_fetch_pdf_text。
📦 安装指南
系统要求
- Node.js 18 及以上版本
- 一个用于 Unpaywall 请求的电子邮件地址（Unpaywall 要求提供该地址以确保礼貌使用）
安装步骤
# 安装依赖
npm install
# 构建项目
npm run build
# 运行项目（使用 stdio 传输，这是 MCP 客户端所要求的）
UNPAYWALL_EMAIL=you@example.com npm start
如果你想在开发环境中使用热加载（无需构建步骤），可以运行以下命令：
UNPAYWALL_EMAIL=you@example.com npm run dev
💻 使用示例
工具调用示例
根据你的 MCP 客户端不同，结构可能会有所不同，但核心负载如下：
// 搜索标题
{
"name": "unpaywall_search_titles",
"arguments": {
"query": "graph neural networks survey",
"is_oa": true,
"page": 1
}
}
// 获取 DOI 的最佳开放获取链接
{
"name": "unpaywall_get_fulltext_links",
"arguments": {
"doi": "10.48550/arXiv.1812.08434"
}
}
// 获取并提取 PDF 文本（通过 DOI）
{
"name": "unpaywall_fetch_pdf_text",
"arguments": {
"doi": "10.48550/arXiv.1812.08434",
"truncate_chars": 20000
}
}
在 MCP 客户端中配置
推荐配置（无需构建）
使用 npm/npx 为 Claude Desktop 进行配置：
{
"mcpServers": {
"unpaywall": {
"command": "npx",
"args": ["-y", "unpaywall-mcp"],
"env": {
"UNPAYWALL_EMAIL": "you@example.com"
}
}
}
}
替代配置（本地仓库）
使用编译后的 dist 文件进行配置：
{
"mcpServers": {
"unpaywall": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {
"UNPAYWALL_EMAIL": "you@example.com"
}
}
}
}
添加配置后，让你的客户端列出工具并尝试以下操作：
- 使用
query参数调用unpaywall_search_titles - 使用
doi参数调用unpaywall_get_fulltext_links - 使用
doi（或pdf_url）参数调用unpaywall_fetch_pdf_text
📚 详细文档
工具说明
unpaywall_get_by_doi
- 描述：通过 DOI 获取 Unpaywall 元数据
- 输入参数：
doi（字符串，必填）：例如10.1038/nphys1170email（字符串，可选）：如果提供，将覆盖UNPAYWALL_EMAIL环境变量
- 输出：来自 Unpaywall 的 JSON 响应
unpaywall_search_titles
- 描述：在 Unpaywall 中搜索与查询匹配的文章标题（每页 50 条结果）
- 输入参数：
query（字符串，必填）：标题查询字符串is_oa（布尔值，可选）：如果为true，仅返回开放获取的结果；如果为false，仅返回封闭访问的结果；不提供则返回所有结果page（整数，大于等于 1，可选）：页码email（字符串，可选）：覆盖UNPAYWALL_EMAIL环境变量
- 输出：来自
GET https://api.unpaywall.org/v2/search的 JSON 搜索结果
unpaywall_get_fulltext_links
- 描述：返回 DOI 的最佳开放获取 PDF URL 和开放 URL，以及所有开放获取的位置
- 输入参数：
doi（字符串，必填）email（字符串，可选）：覆盖UNPAYWALL_EMAIL环境变量
- 输出：包含以下字段的 JSON：
best_pdf_url、best_open_url、best_oa_location、oa_locations以及部分元数据
unpaywall_fetch_pdf_text
- 描述：下载并提取 DOI 的最佳开放获取 PDF 文本，或从提供的
pdf_url中提取文本 - 输入参数：
pdf_url（字符串，可选）：直接的 PDF URL（优先使用）doi（字符串，可选）：如果未提供pdf_url，则用于解析最佳开放获取 PDFemail（字符串，可选）：如果使用doi且未设置UNPAYWALL_EMAIL环境变量，则为必填项truncate_chars（整数，大于等于 1000，可选）：返回的提取文本的最大字符数（默认 20000）
- 输出：包含
text（可能被截断）、length_chars、truncated、pdf_url以及 PDF 元数据的 JSON
LLM 提示技巧（MCP）
当从支持 MCP 的 LLM 客户端使用此服务器时，建议向模型提出以下要求：
- 先搜索再获取：使用
unpaywall_search_titles输入简洁的标题短语进行搜索；选择一个结果；然后对所选的 DOI 调用unpaywall_get_fulltext_links或unpaywall_fetch_pdf_text。 - 优先选择开放获取：当你只需要开放获取的资源时，在搜索中传递
is_oa: true。 - 控制文本大小：在
unpaywall_fetch_pdf_text中设置truncate_chars（默认 20000），并在处理长文本之前进行总结。 - 保持弹性：如果最佳 PDF URL 缺失，可以回退到
best_open_url并从着陆页提取内容（此操作在本服务器之外）。 - 遵守速率限制：如果进行多次调用，请合理安排请求时间；重用之前的响应，而不是重复相同的调用。
以下是一些给 LLM 的良好用户指令示例：
- "查找 3 篇关于 '生物医学基础模型' 的开放获取论文，然后提取并总结其中最佳论文的引言部分。"
- "搜索 '2024 年图神经网络综述'，尽可能筛选出开放获取的结果，然后获取 PDF 文本并生成一个 10 点的总结。"
🔧 技术细节
维护者发布到 npm 的步骤
# 1) 构建项目（发布时也会自动运行）
npm run build
# 2) 提升版本号（选择 patch/minor/major）
npm version patch
# 3) 发布（确保你已登录：npm login）
npm publish --access public
# 4) 在 GitHub 上标记发布版本（可选，推荐）
用户可以按照上述方式使用 npx -y unpaywall-mcp 配置他们的 MCP 客户端，无需克隆或构建项目。
📄 许可证
请参考项目中的 LICENSE 文件获取详细的许可证信息。
⚠️ 重要提示
- 请遵守 Unpaywall 的速率限制和使用指南：https://unpaywall.org/products/api
- 本服务器使用 stdio 传输和
@modelcontextprotocol/sdk。 - 请设置
UNPAYWALL_EMAIL环境变量或在每次调用时传递email参数，以便 Unpaywall 可以就使用情况与你联系。