Unpaywall MCP 服务器

一个公开 Unpaywall 工具的 MCP (Model Context Protocol) 服务器，以便 AI 客户端可以：

• 通过 DOI 获取元数据

• 搜索文章标题

• 检索最佳 OA 全文链接

• 下载并从 OA 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。

您无需克隆此仓库或运行 npm install — npx 会在首次调用时处理获取和缓存。

Related MCP server: ScholarScope MCP

要求

• Node.js 18+ (用于 npx)

• 用于 Unpaywall / OpenAlex 请求的电子邮件地址（Unpaywall 要求，用于 OpenAlex 的礼貌池）。

本地开发（仅限贡献者）

最终用户应使用上述 npx 配置。从源码构建的贡献者请使用：

npm install
npm run build
UNPAYWALL_EMAIL=you@example.com npm start   # stdio transport, as required by MCP clients

热运行（无构建步骤）：

UNPAYWALL_EMAIL=you@example.com npm run dev

工具

unpaywall_get_by_doi

• 描述：获取 DOI 的 Unpaywall 元数据

• 输入模式：

  • doi (字符串，必填)：例如 10.1038/nphys1170

  • email (字符串，可选)：如果提供，将覆盖 UNPAYWALL_EMAIL

• 输出：来自 Unpaywall 的 JSON 响应

unpaywall_search_titles

• 描述：搜索文章标题并为每个命中结果返回 Unpaywall 风格的 OA 元数据（每页 50 个结果）

• 输入模式：

  • query (字符串，必填)：标题查询

  • is_oa (布尔值，可选)：如果为 true，则仅返回 OA 结果；如果为 false，则仅返回闭源结果；省略则返回全部

  • page (整数 >= 1，可选)：页码

  • email (字符串，可选)：覆盖 UNPAYWALL_EMAIL

• 输出：匹配 Unpaywall 搜索格式的 JSON — results[].response 是一个 DOI 风格的记录（doi、title、is_oa、oa_status、best_oa_location、oa_locations），每个结果包含 score 和 snippet。_source: "openalex" 标记了上游来源。

• 注意：由 OpenAlex 的 /works 端点支持，因为 Unpaywall 自己的 /v2/search 自 2025 年 5 月重写以来一直返回 HTTP 500。Unpaywall 现在作为 OpenAlex 的子程序运行，因此这是规范的现代等效方案。

unpaywall_get_fulltext_links

• 描述：返回 DOI 的最佳 OA PDF URL 和 Open URL，以及所有 OA 位置

• 输入模式：

  • doi (字符串，必填)

  • email (字符串，可选)：覆盖 UNPAYWALL_EMAIL

• 输出：包含以下字段的 JSON：best_pdf_url、best_open_url、best_oa_location、oa_locations 以及部分元数据

unpaywall_fetch_pdf_text

• 描述：下载并从 DOI 的最佳 OA PDF 中提取文本，或从提供的 pdf_url 中提取

• 输入模式：

  • pdf_url (字符串，可选)：直接 PDF URL（优先级最高）

  • doi (字符串，可选)：如果未提供 pdf_url，则用于解析最佳 OA 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。

• 优先选择 OA：当您只需要开放获取内容时，在搜索中传递 is_oa: true。

• 控制大小：在 unpaywall_fetch_pdf_text 中设置 truncate_chars（默认 20000），并在继续之前总结长文本。

• 保持弹性：如果缺少最佳 PDF URL，请回退到 best_open_url 并从落地页提取内容（在此服务器之外）。

• 遵守速率限制：如果进行大量调用，请间隔请求；重复使用之前的响应，而不是重复相同的调用。

给 LLM 的良好用户指令：

• “查找 3 篇关于‘生物医学中的基础模型’的 OA 论文，然后提取并总结最好的一篇的引言。”

• “搜索‘Graph Neural Networks survey 2024’，如果可能请过滤为 OA，然后获取 PDF 文本并生成 10 点摘要。”

工具调用负载示例

根据您的 MCP 客户端，结构会有所不同；核心负载为：

// Search titles
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// Get best OA links for a DOI
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// Fetch and extract PDF text (by DOI)
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

在 MCP 客户端中配置

推荐（无需构建）的 Claude Desktop 配置，使用 npm/npx：

{
  "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 的速率限制和使用指南：https://unpaywall.org/products/api

• 服务器使用 stdio 传输和 @modelcontextprotocol/sdk。

• 设置 UNPAYWALL_EMAIL 或在每次调用时传递 email，以便 Unpaywall 可以就使用情况与您联系。

维护者：发布到 npm

# 1) Build the project (also runs automatically on publish)
npm run build

# 2) Bump version (choose patch/minor/major)
npm version patch

# 3) Publish (ensure you are logged in: npm login)
npm publish --access public

# 4) Tag a release on GitHub (optional, recommended)

用户随后可以按照上述说明使用 npx -y unpaywall-mcp 配置其 MCP 客户端。无需克隆或构建。