Mercury402: Treasury/FRED financial data over x402

Mercury402 MCP 服务

这是一个 MCP 服务，可让 Claude 和其他 MCP 客户端发现并调用 Mercury402 的按次付费金融数据 API：美国国债收益率、FRED 序列、外汇、收益率利差、盈亏平衡通胀率、宏观数据包、综合指标和 AI 简报。

Mercury402 通过 x402 按次付费：未付款的请求会返回带有付款说明的 HTTP 402；客户端在 Base 上支付 USDC 后即可获得 JSON 数据。

• **默认（免费）模式：**浏览所有端点及其价格；调用端点会返回 402 中的价格和付款说明。无需钱包，不会花费资金。
• **付费模式（选择启用）：**设置 MERCURY402_PAYER_PRIVATE_KEY 后，服务会支付 402（在 Base 上使用 USDC，每次调用设有上限）并返回数据。

工具

工具	功能	网络	是否花费资金
list_endpoints	列出全部 78 个端点：路径、方法、类别、描述、价格（美元）和参数。可选的 category 和 search 筛选条件。	否	否
get_endpoint_data	调用实时 API 上的端点。返回数据，或返回 402 报价及付款方式。	是	仅限付费模式

get_endpoint_data 参数

参数	类型	说明
path	string	目录中的路径。路径参数可直接写入路径（/v1/fred/UNRATE），也可使用模板（/v1/fred/{series_id}）
params	object	路径参数，以及查询参数（GET）或 JSON 请求体字段（POST）
pay	boolean	仅用于付费模式。false = 返回报价但不付款。默认值为 true

只能调用目录中列出的路径；其他路径会在发起请求前被拒绝。

安装

需要 Node.js 20.10+。此软件包在 npm 上的名称为 mercury402-mcp；MCP 客户端可以通过 npx 启动，因此无需手动安装。

npx -y mercury402-mcp        # starts the server on stdio (what MCP clients do for you)

Claude Code

claude mcp add mercury402 -- npx -y mercury402-mcp

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），然后重启 Claude Desktop：

{
  "mcpServers": {
    "mercury402": {
      "command": "npx",
      "args": ["-y", "mercury402-mcp"]
    }
  }
}

付费模式（可选）

默认情况下，服务绝不会花费资金：它只会列出端点并返回价格报价。如需让它按次付款，请为其提供付款钱包：

警告：私钥以明文形式存储在 MCP 客户端配置中 （claude_desktop_config.json，或 Claude Code 使用的 ~/.claude.json）。请使用只在 Base 上存有少量 USDC 的专用钱包，绝不要使用主钱包，并将 MERCURY402_MAX_PRICE_USD 设为较低值。使用 Claude Code 时，不要通过 --scope project 添加密钥：这会将密钥写入 .mcp.json，该文件通常会提交到 git。

Claude Code：

claude mcp add mercury402 \
  -e MERCURY402_PAYER_PRIVATE_KEY=<dedicated-wallet-private-key> \
  -e MERCURY402_MAX_PRICE_USD=0.50 \
  -- npx -y mercury402-mcp

Claude Desktop：

{
  "mcpServers": {
    "mercury402": {
      "command": "npx",
      "args": ["-y", "mercury402-mcp"],
      "env": {
        "MERCURY402_PAYER_PRIVATE_KEY": "<dedicated-wallet-private-key>",
        "MERCURY402_MAX_PRICE_USD": "0.50"
      }
    }
  }
}

替代方案：从本地检出版本运行

git clone https://github.com/dudman1/mercury402.git
cd mercury402/mcp-server
npm install
npm run build

然后将客户端指向构建后的文件，而不是 npx：

claude mcp add mercury402 -- node /absolute/path/to/mercury402/mcp-server/dist/index.js

{
  "mcpServers": {
    "mercury402": {
      "command": "node",
      "args": ["/absolute/path/to/mercury402/mcp-server/dist/index.js"]
    }
  }
}

Streamable HTTP（可选）

npx -y mercury402-mcp --http   # http://127.0.0.1:3402/mcp (stateless, JSON responses)

无状态 Streamable HTTP：POST /mcp 使用 MCP 协议，GET / 描述服务，GET /healthz 用于本地运行状况检查。HTTP 端点不设身份验证。默认绑定到 127.0.0.1，会根据允许列表（回环地址名称及 MCP_HTTP_ALLOWED_HOSTS）检查 Host 标头，按客户端 IP 和全局频率限制请求，并限制请求正文大小。

HTTP 下的付费模式仅限回环地址。设置 MERCURY402_PAYER_PRIVATE_KEY 后，如果同时将 MCP_HTTP_HOST 设为非回环地址、在 MCP_HTTP_ALLOWED_HOSTS 中添加公网地址、启用 MCP_HTTP_TRUST_PROXY 或设置 MCP_PUBLIC_URL，服务将拒绝启动。付费模式还会拒绝浏览器请求（任何带有 Origin 标头的请求）。如需在免费模式下通过反向代理公开提供服务，请参阅 deploy/HOSTED.md。

环境变量

变量	默认值	描述
MERCURY402_PAYER_PRIVATE_KEY	未设置（关闭付费模式）	用于支付 Base 上 USDC 的钱包 EVM 私钥（十六进制，可省略 0x）。设置此项即可启用付费模式。私钥会以明文形式保存在客户端配置中，因此请使用余额较低的专用钱包。服务仅在进程内使用该私钥签署付款；任何工具或错误都不会记录或返回该私钥
MERCURY402_MAX_PRICE_USD	0.50	每次调用的美元支出上限。若 402 报价超过此上限，系统会将报价返回给 Agent，而不会付款。当前每次调用的价格为 0.05–0.50 美元；范围 FRED 查询的费用为 2 倍
MERCURY402_API_URL	https://api.mercury402.com	API 基础 URL（https://mercury402.uk 也可使用）
MERCURY402_TIMEOUT_MS	60000	每个请求的超时时间（付费调用会等待链上结算）
MCP_HTTP_HOST / MCP_HTTP_PORT	127.0.0.1 / 3402	HTTP 传输绑定地址（仅在使用 --http 时生效）
MCP_HTTP_ALLOWED_HOSTS	未设置	允许的额外 Host 标头名称，以逗号分隔（例如，代理后的 mcp.example.com）。始终接受环回地址名称；其他名称均返回 403
MCP_HTTP_TRUST_PROXY	false	使用 Cloudflare 的 CF-Connecting-IP 而非套接字地址进行速率限制。仅在 cloudflared/Cloudflare 后启用：否则该标头可被伪造。绝不使用 X-Forwarded-For
MCP_HTTP_RATE_LIMIT_PER_MIN	60	每个客户端 IP 每分钟的 POST /mcp 请求数（0 表示禁用）
MCP_HTTP_GLOBAL_RATE_LIMIT_PER_MIN	600	所有客户端每分钟的 POST /mcp 请求总数（0 表示禁用）
MCP_HTTP_MAX_BODY_BYTES	65536	接受的最大请求正文；超过此大小将返回 413
MCP_PUBLIC_URL	未设置	GET / 公布的公开 /mcp URL。设置此项会将服务标记为公开服务，因此付费模式将拒绝启动

工具调用示例

列出财政部端点：

{ "name": "list_endpoints", "arguments": { "category": "treasury" } }

类别：ai、breakeven-inflation、composite、forex、fred、macro、treasury、yield-spread。

获取 FRED 序列（免费模式会返回报价）：

{ "name": "get_endpoint_data", "arguments": { "path": "/v1/fred/UNRATE", "params": { "limit": 12 } } }

PAYMENT REQUIRED (HTTP 402) for https://api.mercury402.com/v1/fred/UNRATE?limit=12: $0.05 (50000 USDC atomic units on base, pay to 0x…). Payment required. Paid mode is disabled (MERCURY402_PAYER_PRIVATE_KEY not set).
{
  "status": "payment_required",
  "quote": { "price_usd": 0.05, "amount_usdc_atomic": "50000", "network": "base", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "pay_to": "0x…", "scheme": "exact", "x402_version": 1 },
  "how_to_pay": ["…"],
  ...
}

历史收益率曲线（POST，参数将成为 JSON 正文）：

{
  "name": "get_endpoint_data",
  "arguments": {
    "path": "/v1/treasury/yield-curve/historical",
    "params": { "start_date": "2026-07-01", "end_date": "2026-09-30" }
  }
}

查询数据（AI，POST）：

{
  "name": "get_endpoint_data",
  "arguments": { "path": "/v1/ai/ask", "params": { "question": "Is inflation cooling?", "series": ["/v1/fred/cpi", "/v1/fred/pce-core"] } }
}

仅获取报价，即使在付费模式下也是如此：

{ "name": "get_endpoint_data", "arguments": { "path": "/v1/composite/economic-dashboard", "pay": false } }

在付费模式下，成功调用会返回 status: "ok"、位于 data 下的端点 JSON，以及包含价格、付款方地址和已解码 PAYMENT-RESPONSE 结算信息（交易哈希）的 payment 区块。

付费模式的工作方式

1. 请求端点；Mercury402 会通过 402 响应返回 x402 付款要求。系统使用 v1 JSON 正文 （x402Version: 1、网络为 base）；v2 Payment-Required 标头则作为备用方案。
2. 服务选择 exact / Base 上 USDC 选项并进行检查：网络为 base（或 eip155:8453），资产为 Base USDC（0x8335…2913），价格 ≤ MERCURY402_MAX_PRICE_USD。否则，服务会返回报价且不付款。
3. 服务会为确切的报价金额签署 EIP-3009 transferWithAuthorization（在本地使用新生成的随机 nonce），然后重新发送请求，并附带 PAYMENT-SIGNATURE 标头，其中包含 base64 编码的 JSON： { x402Version: 2, accepted: <the 402 body's accepts[0]>, payload: { authorization, signature } }。其 格式与 Mercury402 服务端验证的格式相同 （require402Payment()）。Mercury402 会在 链上结算并返回数据。
4. 付费请求绝不会自动重试，因此一次工具调用不会被重复收费。

安全说明：请使用余额较少的专用热钱包，因为私钥以明文形式保存在客户端配置中。服务仅从环境变量读取私钥，在进程内用于签名，绝不会记录、回显或包含在工具输出或错误中。

定价说明

• 大多数端点的费用为 $0.05；宏观经济数据包／衰退概率为 $0.10；AI 简报为 $0.10，AI 提问为 $0.15； 综合数据为 $0.40–$0.50。
• 同时提供 observation_start 和 observation_end 时，/v1/fred/{series_id} 的费用为 2 倍。
• 无效的 FRED 序列 ID 和格式错误的历史日期范围会在任何 402 错误之前免费返回 400 错误。

开发

从 dudman1/mercury402 的代码库检出版本开始：

npm test                    # vitest; HTTP and payments are mocked, no network, no real transactions
                            # test/server-contract.test.ts also boots ../src/server.js (needs `npm ci` at the
                            # repo root; skipped otherwise) with on-chain settlement stubbed
npm run typecheck
npm run generate:catalog    # regenerate src/catalog.json after changing ../src/pricing.js or routes
npm pack --dry-run          # inspect the publish tarball

端点目录（src/catalog.json）由 ../src/catalog.js 生成。该模块也用于构建 API 的 JSON 清单和 /llms.txt（读取 src/pricing.js、src/new-routes.js 和 src/ai-routes.js）。如果目录与 src/pricing.js 不一致，两个包中的测试都会失败。tsc 会将目录打包到 dist/catalog.json 中，因此发布的包在运行时不会读取代码库；prepublishOnly 会重新生成目录、重新构建并运行测试。