Unpaywall MCP

🚀 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/nphys1170
  • email（字符串，可选）：如果提供，将覆盖 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，则用于解析最佳开放获取 PDF
  • email（字符串，可选）：如果使用 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 可以就使用情况与你联系。