在 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 地址发送同样的请求头。

发布于。

后续步骤