Claude Agent SDK で Narwhal API を使う

Narwhal と Claude Agent SDK を組み合わせると、祝日、発表日、経済データ、コモディティ、為替、予測市場について質問できます。APIキーでエージェントを Narwhal MCP に接続し、わかりやすい言葉で質問を渡せば、エージェントが適切なツールを選びます。

セットアップする内容

Claude Agent SDK を使うと、Python からエージェントに質問を渡せます。ここで作るのは、Narwhal MCP に接続し、データ領域ごとに質問を送るスクリプトです。質問は PROMPTS 辞書に入れ、サーバー接続とツールの権限は ClaudeAgentOptions に設定します。スクリプトは各領域の名前と、エージェントが返したメッセージを出力します。

APIキーを設定

  1. 無料の Narwhal キーを作成する narwhalapi.com/signup でキーを作成します。Narwhal は 1 つのアカウントと 1 つの APIキーで各データ API を利用できるため、このスクリプトのすべてのデータ領域に同じキーが使えます。
  2. キーを環境に保存する キーを NARWHAL_API_KEY という環境変数に入れます。Python スクリプトはこの変数を読み込んで Bearer ヘッダーに使い、Claude Code の設定でも名前でこの変数を参照します。エージェントを起動する環境でこの変数が使えるようにしてください。環境変数の値にはキーそのものを設定し、Bearer の接頭辞はヘッダー設定側に残します。
    APIキーの環境変数
    export NARWHAL_API_KEY="YOUR_KEY"

Claude Code から質問する

Claude Code では、JSON 設定で Narwhal を MCP サーバーとして追加できます。Python スクリプトを書かずに質問したい場合は、この方法を使います。サーバーのアドレスは SDK で使う MCP アドレスと同じで、接続タイプは http です。Claude Code にはサーバー設定、Python SDK には ClaudeAgentOptions の設定を使います。

  1. MCP サーバー設定を追加する サーバー名を narwhal にして JSON 設定を追加します。Authorization ヘッダーには環境変数の参照を残してください。そうすると、設定は NARWHAL_API_KEY からキーを読み取ります。
    MCP サーバー設定
    {
  "mcpServers": {
    "narwhal": {
      "type": "http",
      "url": "https://api.narwhalapi.com/mcp",
      "headers": { "Authorization": "Bearer ${NARWHAL_API_KEY}" }
    }
  }
}
  2. わかりやすい言葉で質問する 「2026年12月25日はアメリカの祝日ですか?」と尋ねてみましょう。エージェントは質問からツールを選びます。ほかにも、発表日、経済データ、コモディティ、為替、予測市場の質問例を各領域のサンプルに載せています。

コードでデータを取得する

claude-agent-sdk をインストールし、キーを環境で使える状態にして Python スクリプトを実行します。mcp_servers の設定で MCP の URL と Authorization ヘッダーを指定します。allowed_tools のワイルドカードで、エージェントはすべての Narwhal ツールを使えます。query は呼び出しごとに、質問と共通のオプションを受け取ります。コードでは、asyncio と os に加えて、SDK から ClaudeAgentOptions と query をインポートしています。

SDK をインストールする
pip install claude-agent-sdk
Claude Agent SDK
import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    mcp_servers={
        "narwhal": {
            "type": "http",
            "url": "https://api.narwhalapi.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
        }
    },
    allowed_tools=["mcp__narwhal__*"],
)

PROMPTS = {
    "holidays": "Is 25 December 2026 a public holiday in the United States?",
    "release dates": "When is the US CPI release in November 2026?",
    "economics": "What is the latest US CPI index?",
    "commodities": "What is the Brent spot price in dollars a barrel?",
    "FX": "What are the USD/EUR and USD/IDR rates?",
    "predictions": "What are the Fed rate odds for its next meeting?",
}

async def main():
    for area, question in PROMPTS.items():
        print("##", area)
        async for message in query(prompt=question, options=options):
            print(message)

asyncio.run(main())

PROMPTS のエントリは、自然な文章の質問にしておきます。欲しい情報を言葉で書けば、ツールはエージェントが選びます。ループは質問を 1 件ずつ送り、その領域のメッセージを出力します。特定の領域だけ尋ねるには、以降のサンプルのように、その領域の質問を同じ options で使います。main の中では、async for が query の各メッセージを出力してから、外側のループが次の領域に進みます。個別のサンプルは、完全版スクリプトのインポートと options を再利用し、その領域の質問だけを入れた小さな PROMPTS 辞書を使います。

スケジュールで実行する

cron やジョブランナーからスクリプトを実行し、スケジュール実行されるスクリプトで NARWHAL_API_KEY が使えるようにします。ツール呼び出しが成功するたびに、キーのクレジットから 1 回分を消費します。スクリプトは PROMPTS の質問を順に処理するため、スケジュール実行のたびにその辞書にあるすべての領域について質問します。スケジュール実行のエージェントに尋ねさせたい質問は、その辞書に入れておいてください。

Claude Agent SDK で祝日を調べる

特定の日付が祝日かどうかを尋ねます。この質問では日付と国の両方を指定しています。対応する REST は https://api.narwhalapi.com/v1/calendars/holidays/USA/2026 で、holidays を読み取ります。各エントリには date と name があります。サンプルでは、options で定義済みの MCP 接続を使います。

祝日の質問
PROMPTS = {
    "holidays": "Is 25 December 2026 a public holiday in the United States?",
}
async def main():
    async for message in query(prompt=PROMPTS["holidays"], options=options):
        print(message)  # REST counterpart field: holidays

asyncio.run(main())

Claude Agent SDK で発表日を調べる

発表日を知りたいときは、指標名と月を指定して尋ねます。発表日は経済カレンダーから取得します。対応する REST は https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-11-01&end_date=2026-11-30&limit=100 です。releases を読み取ります。各エントリには at、period、topic、status があります。CPI の指数値を知りたい場合は、経済データの質問を使ってください。

発表日の質問
PROMPTS = {
    "release dates": "When is the US CPI release in November 2026?",
}
async def main():
    async for message in query(prompt=PROMPTS["release dates"], options=options):
        print(message)  # REST counterpart field: releases

asyncio.run(main())

Claude Agent SDK で経済データを調べる

経済データのツールを通じて、アメリカの CPI 指数を尋ねます。Narwhal の経済データには、インフレ、GDP、利回りも含まれます。CPI の REST は https://api.narwhalapi.com/v1/economics/USA/cpi/observations?start=2025-09 で、observations に period と value を持つエントリが入っています。プロンプトではエージェントに指数を尋ね、REST の URL では観測値の開始期間を指定します。

CPI の質問
PROMPTS = {
    "economics": "What is the latest US CPI index?",
}
async def main():
    async for message in query(prompt=PROMPTS["economics"], options=options):
        print(message)  # REST counterpart field: observations

asyncio.run(main())

Claude Agent SDK でコモディティを調べる

Brent のプロンプトのように、質問にはコモディティ名と単位を入れます。対応する REST は https://api.narwhalapi.com/v1/commodities/spot/BRENT/USD で、price フィールドを読み取ります。Narwhal のスポットコードには、たとえば XAU、XAG、XPT、XPD、XCU、BRENT、WTI があります。このサンプルは、完全版スクリプトの Brent の質問をそのまま使います。

Brent の質問
PROMPTS = {
    "commodities": "What is the Brent spot price in dollars a barrel?",
}
async def main():
    async for message in query(prompt=PROMPTS["commodities"], options=options):
        print(message)  # REST counterpart field: price

asyncio.run(main())

Claude Agent SDK で為替を調べる

必要な通貨ペアを同じ質問にまとめて尋ねます。このプロンプトは USD/EUR と USD/IDR を求めています。対応する REST は https://api.narwhalapi.com/v1/fx/rates/USD?currencies=EUR,IDR で、各エントリに currency と rate を持つ rates が返ります。プロンプトも URL も通貨を指定しており、MCP のエージェントはプロンプトに合わせてツールを選びます。

為替レートの質問
PROMPTS = {
    "FX": "What are the USD/EUR and USD/IDR rates?",
}
async def main():
    async for message in query(prompt=PROMPTS["FX"], options=options):
        print(message)  # REST counterpart field: rates

asyncio.run(main())

Claude Agent SDK で予測市場を調べる

予測市場のツールを通じて、Fed の政策金利に関する確率を尋ねます。対応する REST は https://api.narwhalapi.com/v1/predictions/policy-paths/federal-reserve です。meetings を読み取ると、各エントリに resolves_at、p_cut、p_hold、p_hike があります。これらは、確定時刻と、利下げ、据え置き、利上げの確率を表します。サンプルは、完全版スクリプトと同じ予測市場の質問をします。

Fed の政策金利確率の質問
PROMPTS = {
    "predictions": "What are the Fed rate odds for its next meeting?",
}
async def main():
    async for message in query(prompt=PROMPTS["predictions"], options=options):
        print(message)  # REST counterpart field: meetings

asyncio.run(main())

エージェントが呼び出せるものを制限するには?

allowed_tools のワイルドカードを、許可したいツール名に置き換えます。CPI なら mcp__narwhal__economics_get_cpi を使います。そのツールを明示するには、ClaudeAgentOptions に allowed_tools=["mcp__narwhal__economics_get_cpi"] を設定します。完全版スクリプトは質問がすべてのデータ領域にわたるため、mcp__narwhal__* を使っています。

自分の Claude へのアクセスは必要ですか?

はい。エージェントの実行には、Narwhal のAPIキーに加えて、ご自身の Claude へのアクセスが必要です。Narwhal のキーは Narwhal へのリクエストを認証するもので、REST と MCP で同じキーを共有します。各領域の URL への REST リクエストでは Authorization: Bearer YOUR_KEY を送ります。SDK の設定も、MCP アドレスへ同じヘッダーを送ります。

公開。

次のステップ