Mercury402: Treasury/FRED financial data over x402

Mercury402 MCP サーバー

Claude やその他の MCP クライアントが、Mercury402 の従量課金型金融データ API（国債利回り、FRED 系列、外国為替、利回りスプレッド、ブレークイーブンインフレ率、マクロバンドル、複合指標、AI ブリーフィング）を検索して呼び出せる MCP サーバーです。

Mercury402 は x402 による呼び出しごとの課金方式です。未払いのリクエストには支払い情報を含む HTTP 402 が返され、クライアントが Base 上で USDC を支払うと JSON が返されます。

• デフォルト（無料）モード： すべてのエンドポイントと価格を参照できます。エンドポイントを呼び出すと、402 の価格と支払い手順が返されます。ウォレットは不要で、支払いも発生しません。
• 有料モード（オプトイン）： MERCURY402_PAYER_PRIVATE_KEY を設定すると、サーバーが 402 の支払い（Base 上の USDC、呼び出しごとに上限あり）を行い、データを返します。

ツール

ツール	内容	ネットワーク	支払い
list_endpoints	78 個すべてのエンドポイントについて、パス、メソッド、カテゴリ、説明、価格（USD）、パラメーターを一覧表示します。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"]
    }
  }
}

ストリーム可能な HTTP（任意）

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

ステートレスなストリーム可能 HTTP では、POST /mcp が MCP として通信し、GET / がサーバーの情報を返し、GET /healthz がローカルのヘルスチェックを行います。HTTP エンドポイントには認証がありません。デフォルトでは 127.0.0.1 にバインドされ、Host ヘッダーを許可リスト（ループバック名および MCP_HTTP_ALLOWED_HOSTS）と照合し、クライアント 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	未設定（有料モードはオフ）	支払いに使用するウォレットのEVM秘密鍵（16進数、0xは省略可能）。Base上のUSDCで支払います。設定すると有料モードが有効になります。クライアント設定に平文で保存されるため、残高の少ない専用ウォレットを使用してください。サーバーは支払いの署名にプロセス内でのみ使用し、ツールやエラーでログに記録したり返したりすることはありません
MERCURY402_MAX_PRICE_USD	0.50	1回の呼び出しあたりの支出上限（USD）。これを超える402見積もりは支払われず、エージェントに返されます。現在の価格は1回あたり$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ごとの1分あたりのPOST /mcpリクエスト数（0で無効）
MCP_HTTP_GLOBAL_RATE_LIMIT_PER_MIN	600	全クライアント合計の1分あたりのPOST /mcpリクエスト数（0で無効）
MCP_HTTP_MAX_BODY_BYTES	65536	受け入れるリクエストボディの最大サイズ。これを超えると413になります
MCP_PUBLIC_URL	未設定	GET /で公開されるパブリックな/mcp URL。設定するとサーバーは公開状態とみなされ、有料モードは起動を拒否します

ツール呼び出しの例

Treasuryのエンドポイントを一覧表示します：

{ "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"、エンドポイントのJSONを含むdata、価格、支払者のアドレス、デコードされたPAYMENT-RESPONSE決済情報（トランザクションハッシュ）を含むpaymentブロックが返されます。

有料モードの仕組み

1. エンドポイントにリクエストを送信します。Mercury402はx402の支払い要件とともに402を返します。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を使ってローカルで署名）。その後、base64 JSON { x402Version: 2, accepted: <the 402 body's accepts[0]>, payload: { authorization, signature } }を含むPAYMENT-SIGNATUREヘッダーを付けてリクエストを再送します。これはMercury402のサーバーが検証するものと同じ形式です （require402Payment()）。Mercury402はオンチェーンで決済し、データを返します。
4. 有料リクエストは自動で再試行されないため、1回のツール呼び出しで二重に課金されることはありません。

セキュリティ上の注意：秘密鍵はクライアント設定に平文で保存されるため、残高の少ない専用のホットウォレットを使用してください。サーバーは環境変数からのみ鍵を読み取り、署名のためにプロセス内で使用します。ログへの記録、値の返却、ツール出力やエラーへの含有は行いません。

料金に関する注意事項

• ほとんどのエンドポイントは $0.05 です。マクロ指標バンドル／景気後退確率は $0.10、AI ブリーフィングは $0.10、AI 質問は $0.15、 複合指標は $0.40～$0.50 です。
• /v1/fred/{series_id} は、observation_start と observation_end の両方を指定すると料金が 2 倍になります。
• 無効な FRED シリーズ ID と不正な過去の日付範囲は、402 が発生する前に無料で 400 を返します。

開発

udman1/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）は、API の JSON マニフェストと /llms.txt を生成するものと同じモジュールである ../src/catalog.js から生成されます（src/pricing.js、src/new-routes.js、src/ai-routes.js を読み込みます）。どちらのパッケージのテストも、src/pricing.js との不整合があると失敗します。tsc はカタログを dist/catalog.json に組み込むため、公開パッケージは実行時にリポジトリを読み込みません。prepublishOnly はカタログを再生成し、ビルドし直して、テストを実行します。