Narwhal API
一个用于金融和经济数据的 API 和 MCP 服务器:涵盖市场、经济、公司等数据。
托管 MCP 服务器
npx add-mcp 'https://api.narwhalapi.com/mcp'可安装到 Claude Code、Codex、Cursor 等客户端
文档
Connect through MCP
Use the same Narwhal key and public API schemas from an MCP client.
Narwhal exposes one stateless Streamable HTTP MCP endpoint. It uses the same enabled data APIs, response schemas, authentication, and credit as REST.
Connect
Add the remote server https://api.narwhalapi.com/mcp to your MCP client. Choose Connect, sign in with your Narwhal account, and choose Allow on the Narwhal consent screen.
If your client cannot sign in, use your API key instead.
Add the remote server URL and Bearer header to an MCP client that supports authenticated Streamable HTTP.
Client-neutral field map
{
"url": "https://api.narwhalapi.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_NARWHAL_API_KEY"
}
}
This is a field map, not a copy-paste file. Replace YOUR_NARWHAL_API_KEY through your client's secure secret setting. JSON does not expand shell variables by itself, and MCP clients use different environment-variable syntax.
Do not paste a real key into a shared configuration file.
Available tools
tools/list returns the public read-only tools enabled for this release profile. The catalogue below is the public tool set, not a promise that every source has a value for every input.
economics_get_cpi economics_get_inflation economics_get_unemployment economics_get_labour_force_participation economics_get_gdp economics_get_gdp_growth economics_get_trade economics_get_cpi_history economics_get_inflation_history economics_get_unemployment_history economics_get_labour_force_participation_history economics_get_gdp_history economics_get_gdp_growth_history economics_get_trade_history economics_get_population_history economics_read_series_observations economics_search_catalogue economics_read_catalogue_series economics_read_catalogue_observations economics_read_catalogue_latest_batch economics_get_policy_rate economics_get_policy_rate_history economics_get_central_bank_reserves economics_get_central_bank_balance_sheet economics_get_rate_decisions trade_list_hs_codes trade_get_hs_code trade_get_coverage trade_get_partners trade_get_products trade_get_product trade_get_flows filings_search_companies filings_get_company filings_get_financials filings_list_company_filings filings_get_filing filings_list_latest_filings filings_list_holders filings_get_as_reported filings_list_insider_trades filings_list_insider_ownership filings_list_insider_statements filings_list_company_insiders filings_list_insider_person_trades filings_list_insider_feed filings_get_insider_activity filings_list_insider_transaction_codes calendars_list_registrations filings_list_beneficial_owners filings_list_investor_beneficial_ownership filings_search_beneficial_ownership_filers filings_search_beneficial_ownership_companies filings_get_sections filings_get_company_sections filings_list_section_items filings_list_institutional_holders filings_list_investor_holdings filings_search_investors filings_list_investor_filings filings_list_fund_holdings filings_list_company_funds fx_get_rates fx_get_rate_history fx_convert_currency fx_get_rate_bars commodities_get_spot_price commodities_get_price_history commodities_list_palmoil_physical_series commodities_get_palmoil_physical_price commodities_get_palmoil_physical_observations commodities_list_physical_series commodities_get_physical_series commodities_get_physical_latest commodities_get_physical_observations economics_list_releases economics_get_release events_list events_get predictions_list_topics predictions_get_topic predictions_list_events predictions_get_scalar predictions_get_extreme predictions_get_timing predictions_get_binary predictions_get_scalar_history predictions_get_extreme_history predictions_get_timing_history predictions_get_binary_history predictions_get_policy_path predictions_get_policy_path_history calendars_list_holidays calendars_get_holidays_on_date calendars_get_next_holiday economics_get_yield_curve economics_get_yield_curve_history
Monitors
A monitor sends a signed JSON event to an HTTPS URL when a new figure arrives. These seven tools create and manage monitors with the same inputs, results and errors as the /v1/webhooks routes. They are not read-only, and they take no credit. A monitor needs a public HTTPS URL that your agent or its backend controls. An agent with no endpoint should poll events_list instead.
| Tool | What it does |
|---|---|
monitors_create | Create a monitor from a URL, countries and families. Returns the signing secret once. |
monitors_list | List the account's monitors and how many it may enable. |
monitors_update | Pause or resume a monitor, or change its URL, countries or families. What you leave out stays as it is. |
monitors_delete | Delete a monitor. |
monitors_send_test | Send a signed test event to the monitor's URL. |
monitors_list_deliveries | List what was sent to the URL, with the status of each attempt. |
monitors_replay_delivery | Send an earlier delivery again. Its event id stays the same. |
The signing secret is shown only in the result of monitors_create. The agent must hand it to the user's backend to store. Each event carries x-narwhal-timestamp and x-narwhal-signature; the backend recomputes the HMAC-SHA256 of the timestamp, a dot and the raw body with the secret and compares it with the signature before it trusts the body. The steps are in the webhooks reference. An account can keep 25 monitors, and all of them can be enabled. A country that no event of the chosen families can reach is refused, and the error names it. The dashboard lists the countries each release type can fire for. An account created by agent sign-up gets account_pending until the user has verified it.
An app sign-in, such as a Claude or ChatGPT connector, cannot manage monitors. The monitor tools are left out of its tool list, and a call answers status 403 with api_key_required. A connection with an API key can manage monitors.
A monitor sends a delivery only when a new figure arrives. A figure changed later, a date change and a cancelled release are not sent and not charged. The families are gdp, prices, labour, trade, policy_rate, yield_curve, predictions and filings, and any other is refused. A monitor fires only for releases Narwhal has for that country.
A release day can produce a calendar event and a data event for one publication. A monitor that matches both gets one delivery: release.updated carries the release and, when the values can be read, the data, and the linked dataset.published event is not sent to the same monitor when that release carries the figure. Every event type, field and example body is in the receive webhooks guide.
Arguments and results
Latest-release tools accept country, optional period and optional version_id. History tools accept country, optional start and end, plus limit and cursor for pagination.
Tool arguments
{
"country": "USA",
"period": "2026-07"
}
| Tool | Period | Other arguments |
|---|---|---|
economics_get_cpi | YYYY-MM | version_id |
economics_get_inflation | YYYY-MM | version_id |
economics_get_unemployment | YYYY, YYYY-MM, or YYYY-QN | version_id |
economics_get_labour_force_participation | YYYY, YYYY-MM, or YYYY-QN | version_id |
economics_get_gdp | YYYY-QN | version_id |
economics_get_gdp_growth | YYYY-QN | version_id |
economics_get_trade | YYYY or YYYY-MM | version_id |
economics_get_cpi_history | YYYY-MM | start, end, limit, and cursor |
economics_get_inflation_history | YYYY-MM | start, end, limit, and cursor |
economics_get_unemployment_history | YYYY-MM or YYYY-QN | start, end, limit, and cursor |
economics_get_labour_force_participation_history | YYYY-MM or YYYY-QN | start, end, limit, and cursor |
economics_get_gdp_history | YYYY-QN | start, end, limit, and cursor |
economics_get_gdp_growth_history | YYYY-QN | start, end, limit, and cursor |
economics_get_trade_history | YYYY-MM | start, end, limit, and cursor |
economics_get_population_history | YYYY | start, end, limit, and cursor |
Successful tool calls return schema-valid structuredContent plus the same JSON serialized as text for client compatibility. MCP problems use the same public status and code vocabulary as REST.
Credit behavior
Initialization and tool discovery cost nothing. Each successful tools/call takes the same credit as the matching REST call, at the price of its API. A tool that takes several ids costs one call for each id.
First tools/call
{
"method": "tools/call",
"params": {
"name": "fx_get_rates",
"arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
}
}
Every account gets $10 free every month. The limit is 50 requests a minute on free credit and 500 once the account holds paid credit. X-Narwhal-Cost and X-Narwhal-Balance show what a call cost and what is left. The X-RateLimit-* headers describe the per-minute limit. Too many requests in a minute return 429 rate_limit_exceeded; a balance that cannot pay for the call returns 402 insufficient_credits.
Troubleshooting
| Symptom | Check |
|---|---|
401 invalid_api_key | Confirm the exact Bearer header and that the key is still active. |
| Connection follows a redirect | Use exactly https://api.narwhalapi.com/mcp without a trailing slash. |
| Tool is missing | Only the public tools listed above are available. |
| Tool returns a problem | Read its structured status, code, detail, and request ID. See Errors and credits. |
Was this page helpful?