mcp-newsapi

MCP NewsAPI.ai

适用于 NewsAPI.ai（Event Registry 新闻智能 API）的 Model Context Protocol（MCP）服务。它让 Claude 等 AI 助手能够搜索新闻文章和事件（围绕同一事件的文章集群）、将名称解析为实体 URI、查看趋势，并跟踪账户的令牌预算。

由 Nubiia 构建并维护 — 面向企业的 AI 自动化与集成服务（MCP、Holded、Pipedrive 等）。想为您的企业打造类似服务？请访问 nubiia.es 与我们联系。

⚠️ NewsAPI.ai 按令牌计费

每次搜索都会消耗您套餐中的令牌，而免费套餐的预算有限。本服务旨在节省用量：

• 结果数量默认设为 10（文章/事件），文章正文默认设为 300 个字符，因此每次调用消耗的令牌更少，也更节省助手的上下文窗口。
• 除非传入 allow_archive: true，否则搜索范围仅限于最近 31 天（涉及的每个年份的历史数据都会额外消耗令牌）。allow_archive 需要 date_start，且 date_start → date_end（默认：今天）的范围最多为 1 年。若 date_start/date_end 超出最近 31 天且未设置 allow_archive，请求会被拒绝并说明原因，而不是静默返回空结果。
• 完全没有筛选条件的搜索会在本地被拒绝，不会消耗任何令牌。
• 会话令牌预算（默认 200 个令牌，见下文）可在请求失控前将其拦截。
• suggest_* 工具和 get_usage 免费 — 搜索前可用它们将实体解析为 URI。
• get_usage 会显示剩余预算。

根据实际账户测算的费用（31 天窗口）：

工具	每次调用的令牌数
search_articles、get_article	1
search_events、get_event（信息）	5
get_event（include_articles）	1
get_trending_concepts	10
suggest_*、get_usage	0

套餐和价格可能会有变动 — 请参阅 newsapi.ai/pricing 和 docs/api-notes.md。

功能

十个只读工具：

• 文章（2 个）：search_articles、get_article
• 事件（2 个）：search_events、get_event
• 自动建议（4 个）：suggest_concepts、suggest_categories、suggest_sources、 suggest_locations
• 趋势（1 个）：get_trending_concepts
• 账户（1 个）：get_usage

共计：10 个工具，全部标记为 readOnlyHint: true — 本服务不会向 NewsAPI.ai 或任何其他地方写入数据。

v1 刻意不涵盖的内容

主题页面和已保存的搜索、分析服务（文本分类、任意文本的情感分析）、故事聚类、文章提及、聚合结果类型（conceptAggr、timeAggr、……）以及多租户配置。

安装

前置条件

• Node.js 22.14 或更高版本
• NewsAPI.ai 账户和 API 密钥，可从 newsapi.ai → Dashboard 获取

从 npm 安装

npm install -g @nubiia/mcp-newsapi

从源代码安装

git clone https://github.com/nubiia-dev/mcp-newsapi.git
cd mcp-newsapi
npm install
npm run build

配置

环境变量

变量	必填	说明
NEWSAPI_AI_API_KEY	是	您的 NewsAPI.ai API 密钥（Dashboard）。这是密钥 — 切勿提交到版本库。
NEWSAPI_AI_MAX_TOKENS_PER_SESSION	否	每个会话中本服务最多可消耗的 NewsAPI.ai 令牌数（直至服务进程重启）。默认值为 200。

export NEWSAPI_AI_API_KEY=your_newsapi_ai_key
export NEWSAPI_AI_MAX_TOKENS_PER_SESSION=200   # optional

会话令牌预算

预算按服务器进程计算：每个启动的 MCP 客户端／服务实例都有自己的计数器，因此两个配置为 200 的客户端合计可消耗 400。重启后会重置。

每次调用都会在发送之前按测得的令牌成本收费（见上表）。如果调用会超出剩余预算，工具会返回错误，说明剩余预算和总预算，以及如何提高预算——不会向 NewsAPI.ai 发送请求。免费工具（suggest_*、get_usage）永远不会被阻止。get_usage 还会在账户余额旁报告会话预算（maxTokens、spentTokens、remainingTokens）。API 直接拒绝的调用（4xx）会退还费用；已被接受后失败的调用（包括返回 {"error"} 正文的 HTTP 200）仍会计费，因为 API 会对此收费。无效值（例如 abc、-5）会回退为 200，并在 stderr 中显示警告；0 会禁用所有付费调用。

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "newsapi": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-newsapi@latest"],
      "env": {
        "NEWSAPI_AI_API_KEY": "your_newsapi_ai_key",
        "NEWSAPI_AI_MAX_TOKENS_PER_SESSION": "200"
      }
    }
  }
}

如果是从源代码安装：

{
  "mcpServers": {
    "newsapi": {
      "command": "node",
      "args": ["/path/to/mcp-newsapi/dist/index.js"],
      "env": {
        "NEWSAPI_AI_API_KEY": "your_newsapi_ai_key"
      }
    }
  }
}

Claude Code 配置

claude mcp add newsapi --env NEWSAPI_AI_API_KEY=your_newsapi_ai_key -- npx -y @nubiia/mcp-newsapi@latest

故障排除

• 在此仓库中启动时出现 sh: mcp-newsapi: command not found。 如果你从克隆的仓库目录启动 Claude Code（或其他 MCP 客户端），npx @nubiia/mcp-newsapi 会解析本地 package.json，而 mcp-newsapi 二进制文件不在 PATH 中。请使用 @latest 固定注册表版本（如上方示例所示），或从其他目录启动客户端。

工具

参数列表（lang、concept_uris、category_uris、source_uris、location_uris、 ignore_source_uris、data_types、types、concept_types）既可接受单个字符串，也可接受字符串数组："lang": "spa" 和 "lang": ["spa"] 等效。

推荐流程：suggest_*（免费）→ search_* → get_*。

suggest_concepts · 只读 · 免费

将名称（“Telefónica”、“Pedro Sánchez”）解析为概念 URI。将 uri 作为 concept_uris 传入搜索，比关键词精确得多。

{ "prefix": "Telefónica", "types": ["org"], "count": 3 }

要搜索公司、人物、地点或组织？ 请先用 suggest_concepts 解析，并将返回的 uri 作为 concept_uris 传入。keyword 用于自由词和主题，常见词的匹配结果会很杂：例如，在西班牙语中使用 keyword: "Telefónica" 也会匹配普通形容词“telefónica”。

suggest_categories、suggest_sources、suggest_locations · 只读 · 免费

同理，可用于类别（news/Business）、出版物（bbc.co.uk）和地点。

search_articles · 只读 · 1 个令牌

必须提供 keyword、concept_uris、category_uris、source_uris、 location_uris 中至少一项。默认值：10 条结果，按最新优先，跳过重复项，最近 31 天，正文长度为 300 个字符。使用 page 分页；响应中包含 total 和 pages。

{
  "concept_uris": ["http://en.wikipedia.org/wiki/Telefónica"],
  "lang": ["spa"],
  "date_start": "2026-10-01",
  "count": 5
}

日期必须是有效的 YYYY-MM-DD 日期，date_end 不得早于 date_start，并且适用上述存档规则（allow_archive 需要提供 date_start，最长为 1 年）。

其他选项：keyword_loc、keyword_search_mode、ignore_keyword、 ignore_source_uris、data_types（news/pr/blog）、sort_by （date/rel/sourceImportance/cosSim）、min_sentiment/max_sentiment、 body_len、include_duplicates、allow_archive。

get_article · 只读 · 1 个令牌

通过 article_uri 获取单篇文章，正文较长（body_len，默认 3000）。

search_events · 只读 · 5 个令牌

事件：关于同一事件的文章集群，包含标题、简短摘要、日期、地点、关键概念和文章数量。适合查询“X 发生了什么”。sort_by: "size" 可优先显示最大的新闻；min_articles_in_event 可过滤杂项内容。

get_event · 只读 · 5 个令牌（其中 1 个用于 include_articles）

通过 event_uri 获取一个事件；或者设置 include_articles: true，获取报道该事件的文章。

get_trending_concepts · 只读 · 10 个令牌

当前热门的人物、组织和地点（对比最近 2 天与最近 2 周），涵盖 news、social、pr 或 blog（部分套餐可能无法使用 blog 趋势；调用失败仍会计费）。这是费用最高的工具：请谨慎调用。

get_usage · 只读 · 免费

availableTokens、usedTokens、remainingTokens。批量搜索前请先检查。

速率限制

本地防护机制会在 Agent 循环失控、耗尽令牌预算前将其拦截：

工具	限制
search_articles、search_events、get_article、get_event	30 次请求/分钟
get_trending_concepts	20 次请求/分钟
suggest_*、get_usage	120 次请求/分钟
其他所有工具（默认）	60 次请求/分钟

API 本身最多允许 5 个并发请求。429/502/503/504 响应以及连接被拒绝/DNS 错误会采用退避策略重试；对于结果不明确的失败（超时、连接重置），不会重试，因为计费请求可能已经扣费。 每次尝试的超时时间为 30 秒。

错误消息

401/403 响应会附带说明，而不只是显示“未授权”：密钥可能错误或已撤销，也可能是账户令牌不足（get_usage 可帮你判断具体原因）。 API 密钥会放在请求正文中发送，不会出现在 URL 中，并且会从所有错误消息中脱敏（包括 HTTP、网络和 JSON 解析错误）。

开发

npm install
npm run build
npm test              # runs entirely against mocks — no network, no API key
npm run test:coverage
npm run lint

完整工作流请参阅 CONTRIBUTING.md；根据实际账户验证的 API 行为请参阅 docs/api-notes.md。

许可证

MIT

相关项目

• @nubiia/mcp-holded — 用于 Holded 开票/会计 API 的 MCP 服务。
• @nubiia/mcp-signaturit — 用于 Signaturit 电子签名 API 的 MCP 服务。