在 Claude Agent SDK 中使用 Narwhal API

透過 Claude Agent SDK 搭配 Narwhal，你可以詢問國定假日、發布日期、經濟數據、大宗商品、外匯和預測市場方面的問題。用 API 金鑰把代理連接到 Narwhal MCP，再用日常語言提問，代理會自行選擇工具。

你將完成的設定

Claude Agent SDK 可以讓你透過 Python 向代理提問。你將得到一個連接 Narwhal MCP 的腳本，它會為每個資料領域各問一個問題。問題放在 PROMPTS 字典中，伺服器連線與工具權限則由 ClaudeAgentOptions 設定。腳本會印出每個領域的名稱和代理回傳的訊息。

設定你的 API 金鑰

  1. 建立免費的 Narwhal 金鑰 在 narwhalapi.com/signup 建立金鑰。Narwhal 的各個資料 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 伺服器設定 新增 JSON 設定，伺服器名稱使用 narwhal。在 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 中的項目保持為自然語言問題。它們描述你想要的資訊，工具由代理自行選擇。迴圈會逐個傳送問題，並印出該領域的訊息。如果只想詢問某個領域，就依照後面的範例，用該領域的問題搭配同樣的 options。在 main 內，async for 會先印出 query 的每則訊息，外層迴圈才會轉到下一個領域。各個單獨的範例沿用完整腳本中的匯入和 options，只是 PROMPTS 字典更小，只含該領域的問題。

按排程定時執行

透過 cron 或工作排程器執行腳本，並確保排程執行的腳本能讀取 NARWHAL_API_KEY。每次成功的工具呼叫會消耗該金鑰額度中的一次呼叫。腳本會遍歷 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 位址則指定觀測值的起始期間。

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，回傳的 rates 中每個項目都有 currency 和 rate。提示詞和 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 查詢預測市場

透過預測市場工具詢問聯準會利率的機率。對應的 REST 位址是 https://api.narwhalapi.com/v1/predictions/policy-paths/federal-reserve。讀取 meetings，其中每個項目都有 resolves_at、p_cut、p_hold 和 p_hike。這些欄位分別表示結算時間，以及降息、維持不變和升息的機率。範例提出的預測市場問題與完整腳本相同。

聯準會利率機率提問
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 位址傳送同樣的標頭。

發布於 。

後續步驟