Synergic-APIs

Synergic APIs — MCP 服务

Synergic APIs 的官方 Model Context Protocol 服务：为 AI Agent 提供美国官方经济数据。它让 Claude、Cursor 和任何兼容 MCP 的客户端都能直接访问：

• 美国通胀 API — 美国劳工统计局发布的官方 CPI-U：包含 11 个类别，按照美国劳工统计局的方式计算同比／环比变化率，月度历史数据可追溯至1913 年，并提供官方年度平均值。
• 知名商品价格 — 美国鸡蛋、汽油、牛奶、面包、碎牛肉、咖啡和电力的平均价格，月度数据始于 1976 年。
• 美国国债 API — 美国财政部精确到美分的债务数据，涵盖自 1993 年以来的每个工作日、可追溯至1790 年的年度未偿债务，以及财政部支付的平均利率。

所有金额均为 JSON 数字，时间段格式为 YYYY-MM／YYYY-MM-DD。官方记录中缺失的月份会以 null 提供，绝不编造数据。

要求

• Node.js 18.17+（包含 npx）。
• Synergic APIs 密钥。免费获取（无需信用卡）：synergicapis.com/signup.html — 每月 500 次请求，可使用两个 API 的完整历史数据。付费方案请访问 synergicapis.com/pricing.html。

安装

服务通过 npx 使用 stdio 运行，无需克隆或构建。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（设置 → Developer → Edit Config）：

{
  "mcpServers": {
    "synergic-apis": {
      "command": "npx",
      "args": ["-y", "@synergic-apis/mcp"],
      "env": {
        "SYNERGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code

claude mcp add synergic-apis --env SYNERGIC_API_KEY=YOUR_API_KEY -- npx -y @synergic-apis/mcp

Cursor

将以下内容添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "synergic-apis": {
      "command": "npx",
      "args": ["-y", "@synergic-apis/mcp"],
      "env": {
        "SYNERGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

配置

变量	必填	默认值	说明
SYNERGIC_API_KEY	是	—	你的 API 密钥。每次请求都会通过 X-Api-Key 发送。
SYNERGIC_GATEWAY_URL	否	https://api.synergicapis.com	网关基础 URL（可覆盖以用于测试）。

工具

工具	功能	关键参数
get_us_inflation_latest	所有 11 个类别最新月份的 CPI 及同比／环比变化率。	adjusted（可选）
get_us_inflation_history	单个类别的月度 CPI 历史数据（总体 CPI 可追溯至 1913 年）。	category、start／end（YYYY-MM）、limit（≤100）、adjusted
get_us_inflation_annual	官方年度平均 CPI（M13，NSA）。limit=150 = 完整的总体 CPI 序列。	category、start／end（YYYY）、limit（≤150）
get_famous_prices	最新的美国知名商品价格篮子，或单种商品的月度历史数据。	item（可选）、start／end（YYYY-MM）、limit（≤100）
get_us_debt_latest	截至今天、精确到美分的美国国债。	—
get_us_debt_history	日度债务数据（1993 年起，limit ≤100）或财政年度末年度债务数据（1790 年起，limit=250 = 完整序列）。	frequency（daily／annual）、start／end（YYYY-MM-DD）、limit
get_us_interest_rates	各类证券最新的财政部平均利率，或单个类别的月度历史数据（2001 年起）。	security_class（可选）、start／end（YYYY-MM-DD）、limit（≤100）
get_my_usage	你的密钥对应的方案、已用请求数、月度限额和重置日期。	—

历史数据工具按时间段范围分页：如果响应中的 meta.next_end 不为 null，请再次调用该工具，并将 end 设为该值，以获取更早的数据。

试试看

可以向助手提出以下问题：

• “美国当前的总体和核心通胀率是多少？”
• “绘制一下 2020 年以来鸡蛋的价格走势。”
• “过去 12 个月美国国债增加了多少？”
• “今天财政部支付的国库券利率与 2021 年相比如何？”

故障排除

• “SYNERGIC_API_KEY is not set” — 如果缺少密钥，服务会在启动时退出。将其添加到 MCP 客户端配置的 env 块中（见上文），然后重启客户端。
• “Invalid API key” — 网关拒绝了密钥（输入错误或密钥已撤销）。密钥格式类似 sk_...。请前往 synergicapis.com/signup.html 获取新密钥。
• “Rate limit exceeded … retry after Xs” — 你已达到套餐的每分钟限额（免费套餐：10 次请求/分钟）。请稍后重试。
• “Monthly quota exhausted” — 你已用完本月的请求额度（免费套餐：500 次）。请让 Agent 调用 get_my_usage 查看详情，等到 1 日（UTC）额度重置，或前往 synergicapis.com/pricing.html 升级。
• 客户端中未显示工具 — 检查客户端的 MCP 日志；最常见的原因是 Node 版本过旧（需要 18.17+），或客户端使用的 PATH 中没有 npx。在终端中运行 npx -y @synergic-apis/mcp 应在标准错误输出中打印 ready on stdio，然后等待输入。
• 企业代理 / 可自托管测试 — 将 SYNERGIC_GATEWAY_URL 指向你的网关；该服务只会发送带有 X-Api-Key 的 GET 请求。

开发

npm install
npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest — tool→request mapping + error mapping, fetch mocked
npm run build       # emits dist/ and the synergic-apis-mcp bin

数据来源与许可证

数据：美国劳工统计局和美国财政部财政数据（属于公有领域；本产品不受任一机构认可，也与任一机构无关）。 代码：MIT。