altmetric-mcp

Altmetric MCP 服务

模型上下文协议（MCP）服务，可让 AI Agent 访问 Altmetric API，以追踪研究成果在新闻媒体、政策文件、社交媒体和其他在线平台上的关注度和传播范围。

Altmetric 会监测研究成果在传统学术引用之外的讨论情况，包括主流媒体报道、政策引用、专利引用和社交媒体互动，从而全面呈现研究在现实世界中的影响。

有两种连接方式：

• 托管服务（推荐） — 将 AI 客户端指向 https://mcp.altmetric.com/mcp，并使用 Altmetric 帐户登录。无需复制或存储 API 密钥，并且会自动获得你有权使用的工具（Explorer、Details Page 或两者）。从这里开始。
• 本地运行 — 在自己的计算机上使用自己的 API 密钥，通过 stdio 运行服务。适用于离线使用，或希望自行管理密钥的情况。请参阅下文的使用自己的 API 密钥在本地运行。

所需访问权限

该服务只需拥有 Altmetric 的任一 API 的访问权限即可运行——Details Page API 或 Explorer API，并为你提供相应 API 的工具。要充分发挥 Altmetric 的潜力，强烈建议同时拥有两者，因为它们能回答不同的问题：

• Details Page API — 按标识符（DOI、PubMed ID 等）查询特定研究成果的关注度，并按时间范围搜索近期关注度。
• Explorer API — 在整个 Altmetric 数据库以及你所在机构的研究成果中搜索、筛选和汇总研究成果、提及、受众人口统计信息和期刊。

只有其中一个 API 时，你只能使用该 API 对应的工具。请参阅工具，了解每个 API 提供哪些工具；如果缺少某个 API，请申请 API 访问权限。

连接到托管服务（推荐）

在 AI 客户端中使用 Altmetric 最简单的方式，是连接托管服务 https://mcp.altmetric.com/mcp。将客户端指向该 URL，并在提示时使用 Altmetric 帐户登录——客户端会在浏览器中运行标准 OAuth 流程，因此无需复制或存储 API 密钥。你将获得帐户有权使用的全部工具。

Claude Desktop

1. 打开设置 → 自定义 → 连接器，然后点击添加自定义连接器。
2. 将其命名为 Altmetric，并输入 URL https://mcp.altmetric.com/mcp。
3. 点击添加，然后点击连接，并在浏览器窗口打开时登录。

通过向 Claude 提问来验证："使用 Altmetric 工具查询 DOI 10.1038/nature12373 的关注度评分"

Claude Code

claude mcp add --transport http altmetric https://mcp.altmetric.com/mcp

然后在 Claude Code 中运行 /mcp，选择 altmetric 并完成身份验证——浏览器窗口会打开供你登录。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "Altmetric": {
      "url": "https://mcp.altmetric.com/mcp"
    }
  }
}

首次使用该服务时，Cursor 会在浏览器中启动登录流程。

VS Code（GitHub Copilot）

添加到 .vscode/mcp.json（VS Code 1.101 或更高版本）：

{
  "servers": {
    "Altmetric": {
      "type": "http",
      "url": "https://mcp.altmetric.com/mcp"
    }
  }
}

打开命令面板，运行 MCP: List Servers，选择 Altmetric 并启动；在提示时登录。

ChatGPT

打开设置 → 连接器 → 高级并启用开发者模式，然后依次打开设置 → 连接器 → 添加自定义连接器，输入 https://mcp.altmetric.com/mcp 并完成 OAuth 登录。需要付费套餐（Plus、Pro、Business、Enterprise 或 Edu）；免费套餐不提供自定义连接器。所有 Altmetric 工具均为只读，因此 Plus/Pro 套餐的只读限制不会影响这些工具。

其他 MCP 客户端

任何支持带 OAuth 的 Streamable HTTP 传输方式的客户端都可以连接。将其指向 https://mcp.altmetric.com/mcp。首次请求时，服务会返回 401，并附带指向发现文档（/.well-known/oauth-protected-resource）的 WWW-Authenticate 标头，客户端会据此自动通过 Altmetric Explorer 运行 OAuth 流程。

登录方式

托管服务是一个 OAuth 2.1 资源服务。客户端会从 Altmetric Explorer（授权服务）获取 mcp 范围的承载令牌。服务会用该令牌查询你账户的权限，并代表你调用 Altmetric API——你的承载令牌绝不会被转发到这些 API。公布的工具集会根据你的权限显示，因此你只能看到自己有权使用的产品对应的工具。

示例提示词

连接后，用自然语言提问——客户端会选择相应的工具。以下每条提示词都会使用不同的工具：

你只能看到账户有权使用的工具，因此 Explorer 提示词需要机构权限。完整工具集见下文的工具。

数据来源和许可

每个工具都会调用 Altmetric 自有的 API——Details Page API 和 Explorer API，它们都是 Altmetric（Digital Science）的第一方服务。服务不会代理第三方 API，也不持有任何第三方数据。

这些 API 返回的数据包含根据 Altmetric 与第三方平台签订的协议所收集的关注度信息，其中有一项协议会影响返回的数据。根据 Altmetric 与 X（原 Twitter）的许可协议，来自 X 的提及仅包含数字标识符：任何权限层级、任何一个 API 都不会返回账户用户名、显示名称或帖子文本。可获取数量、ID 和汇总人口统计数据，但无法获取具名账户。请参阅 X 提及和 Altmetric API 中的 X 数据。

其他所有来源——新闻媒体、博客、Bluesky、Reddit、播客、政策文件、专利——都会返回具名信息。

使用自己的 API 密钥在本地运行

更倾向于自行运行服务——离线使用或直接管理 API 密钥？通过 npx 以 stdio 方式运行。

前置条件

• Node.js 20.6.0 或更高版本——建议使用仍受积极支持的 LTS 版本（下载）
• Altmetric API 凭据（至少需要一种，建议两种都准备——参见上文的所需权限）：
  • Details Page API 密钥——免费层级或商业权限
  • Explorer API 密钥 + 密钥——机构权限

还没有密钥？申请 API 访问权限

快速安装（macOS 上的 Claude Desktop）

在终端中运行引导式安装程序——它会检查 Node.js、提示输入 API 密钥，并自动配置 Claude Desktop：

bash <(curl -fsSL https://raw.githubusercontent.com/altmetric/altmetric-mcp/main/install.sh)

或者，如果你已克隆此仓库：

bash install.sh

更倾向于手动设置？请参阅下方针对各客户端的说明。

手动配置

配置 MCP 客户端，使用 npx 运行服务。仅包含你有权使用的 API 凭据。

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "altmetric-mcp"],
  "env": {
    "ALTMETRIC_DETAILS_API_KEY": "your_details_api_key_here",
    "ALTMETRIC_EXPLORER_API_KEY": "your_explorer_api_key_here",
    "ALTMETRIC_EXPLORER_API_SECRET": "your_explorer_api_secret_here"
  }
}

claude mcp add --transport stdio altmetric-mcp \
  --env ALTMETRIC_DETAILS_API_KEY=your_details_api_key_here \
  --env ALTMETRIC_EXPLORER_API_KEY=your_explorer_api_key_here \
  --env ALTMETRIC_EXPLORER_API_SECRET=your_explorer_api_secret_here \
  -- npx -y altmetric-mcp

{
  "servers": {
    "Altmetric": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "altmetric-mcp"],
      "env": {
        "ALTMETRIC_DETAILS_API_KEY": "your_details_api_key_here",
        "ALTMETRIC_EXPLORER_API_KEY": "your_explorer_api_key_here",
        "ALTMETRIC_EXPLORER_API_SECRET": "your_explorer_api_secret_here"
      }
    }
  }
}

{
  "mcpServers": {
    "Altmetric": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "altmetric-mcp"],
      "env": {
        "ALTMETRIC_DETAILS_API_KEY": "your_details_api_key_here",
        "ALTMETRIC_EXPLORER_API_KEY": "your_explorer_api_key_here",
        "ALTMETRIC_EXPLORER_API_SECRET": "your_explorer_api_secret_here"
      }
    }
  }
}

安全部署本地服务

本地服务作为 MCP 宿主（Claude Desktop、Claude Code 等）的子进程运行。将其接入敏感工作流之前，有几点值得了解。

服务的行为

• 通过出站 HTTPS 向两个 Altmetric HTTP API 提供只读代理。唯一的例外是对 Explorer identifier_lists 端点执行幂等的 POST（创建或查找），在内部用于将 Explorer 查询限定到给定的一组标识符；它不会创建用户可见的状态，也不会执行破坏性操作。
• 没有入站网络暴露面；不执行破坏性操作。
• 将上游文本视为不可信内容：扫描提示词注入标记，在面向大模型的摘要中隐藏可疑匹配项，并仅通过 structuredContent 提供原始值。

你应采取的措施

• 通过 MCP 宿主的 env 块设置 API 密钥，不要使用已提交的 .env 文件。密钥会出现在 URL 查询字符串中；请将其视为等同于持有者凭据的敏感信息。
• 如果宿主支持，请使用较低权限运行。 此服务只需要通过出站 HTTPS 连接 api.altmetric.com 和 www.altmetric.com。如果宿主或容器运行时支持，请禁止对 $TMPDIR 以外的文件系统进行写入，并禁止其他网络出站流量。
• 考虑设置出站流量允许列表（正向代理 / DLP）。 如果你在处理敏感数据的环境中使用此服务，请通过只允许访问两个 Altmetric 主机的代理路由出站流量。此服务无需与其他主机通信。
• 遵守数据分类区要求。 此服务会将工具参数原样转发给第三方。如果提示词包含受限或受监管的数据，这些数据就会离开你的边界。

已为你实施的防护

• 确保出站 URL 使用 https:。
• 将上游响应限制为 20 MB 和 60 s。
• 将传入工具参数限制为总计 8 MB／每个字符串 64 KB。
• 在调用上游之前，在客户端验证筛选值（日期格式、长度、分页范围）。
• 上游错误正文仅按 SHA-256 前缀记录到 stderr，不会原样记录。

有关漏洞报告和支持的版本，请参阅 SECURITY.md。

故障排除

API 层级

Details Page API

• 免费层级： 可使用 get_citation_counts 和 search_citations
• 商业层级： 可使用所有 Details Page 工具，包括 get_citation_details

如果你尝试使用免费 API 密钥调用 get_citation_details，将收到 403 错误。

Explorer API

• 仅限机构访问： 所有 Explorer API 工具都需要机构凭据
• 可访问整个 Altmetric 数据库中的研究成果和关注度数据
• 集成了数据的组织还可以单独访问其自身的机构研究成果
• 支持按作者、院系、期刊和自定义组织元数据进行高级筛选

工具

此服务通过两个 API 提供 12 种工具：

所有 Explorer 工具还支持 researcher_id 和 grant_id 筛选条件（Dimensions ID），以及用于将查询范围限定为原始学术标识符列表的 identifiers 参数；服务会为你构建相应的标识符列表。Explorer 响应还包含情感数据（研究成果中的 sentiment-analysis-totals，以及 X/Bluesky 提及中的 sentiment-analysis）。

详细参数和示例请参阅 TOOLS.md。

API 文档

• 详情页 API： https://docs.altmetric.com/details-page-api/
• Explorer API： https://docs.altmetric.com/explorer-api/

许可证

MIT