fin-data-mcp-server

A one-stop Model Context Protocol server for free financial market data. It wires up live API requests across 13 market-data categories, focused on sources that need no API key — so it works the moment you start it.

83 no-key tools (15 providers) work out of the box; adding optional free keys unlocks 7 more providers for up to 110 tools / 22 providers, spanning stocks, indices, options, FX, commodities, crypto (spot + perpetual futures), energy, prediction markets, macroeconomics, filings/news, flight tracking, sentiment, and congressional trading. Equities have two independent no-key backends (Yahoo + Cboe) plus optional premium ones.

Keyed providers register only when their key is set — with no keys configured, their tools never appear in tools/list, so the agent never sees a tool it can't use. The fin-data://catalog resource still lists them as "set X to enable."

Built to the MCP best-practices guide: every tool is read-only with proper annotations, validated inputs (Zod), structured content, character-limit truncation, actionable error messages, server instructions, and a discovery resource. Every endpoint was verified returning HTTP 200 from a US IP.

Install

No clone, no build — the server runs straight from GitHub via npx (it builds on first install). Pick your client:

Claude Code (one command)

claude mcp add fin-data -- npx -y github:CohenD/fin-data-mcp

That's it — restart Claude Code and the tools are available. To unlock keyed providers, append env flags, e.g.:

claude mcp add fin-data \
  -e SEC_USER_AGENT="you@example.com" \
  -e FRED_API_KEY=xxxx \
  -- npx -y github:CohenD/fin-data-mcp

Claude Desktop / Cursor / Windsurf / any MCP client

Add this to the client's MCP config (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "fin-data": {
      "command": "npx",
      "args": ["-y", "github:CohenD/fin-data-mcp"],
      "env": { "SEC_USER_AGENT": "you@example.com" }
    }
  }
}

Vercel AI SDK (agentic apps)

import { experimental_createMCPClient as createMCPClient } from "ai";
import { Experimental_StdioMCPTransport as StdioMCPTransport } from "ai/mcp-stdio";

const mcp = await createMCPClient({
  transport: new StdioMCPTransport({
    command: "npx",
    args: ["-y", "github:CohenD/fin-data-mcp"],
  }),
});
const tools = await mcp.tools(); // pass straight into generateText / streamText

Full runnable example: examples/ai-sdk-agent.ts.

From source

git clone https://github.com/CohenD/fin-data-mcp && cd fin-data-mcp
npm install            # builds dist/ via the prepare script
npm start              # run over stdio

A project-scoped .mcp.json is included, so opening the cloned repo in Claude Code auto-registers the server.

No configuration is required for the 83 no-key tools. To unlock keyed providers or higher limits, set the env vars in .env.example.

The server also exposes a fin-data://catalog resource listing every provider, its category, whether it needs a key, and its tools.

Verify it works

npm run smoke                   # broad live sample incl. chained discovery
npx tsx scripts/smoke.ts        # core no-key endpoints
npx tsx scripts/mcp-test.ts     # full MCP handshake: tools/list, resource, a tool call

Tools by category

Category	Provider	Tools
Stocks / Indices / FX / Crypto	Yahoo Finance	yahoo_chart, yahoo_quote, yahoo_search, yahoo_quote_summary, yahoo_recommendations, yahoo_spark
Stocks / Indices / Options (no-key backup)	Cboe	cboe_quote, cboe_history, cboe_options_chain
Options	Yahoo Finance	yahoo_options_chain
Stocks (premium backup, free key)	Tiingo	tiingo_eod_prices, tiingo_metadata, tiingo_iex_intraday
Forex	Frankfurter (ECB)	fx_latest_rates, fx_historical_rate, fx_timeseries, fx_list_currencies
Forex	ExchangeRate-API	fx_open_rates
Commodities / Macro / Demographics	World Bank	worldbank_indicator, worldbank_search_indicators, worldbank_list_countries, worldbank_sources, worldbank_topics, worldbank_indicator_metadata, worldbank_country
Crypto (spot + perp futures)	OKX	crypto_candles, crypto_ticker, crypto_orderbook, crypto_funding_rate, crypto_open_interest, crypto_mark_price, crypto_recent_trades, crypto_all_tickers, crypto_index_candles, crypto_price_limit, crypto_long_short_ratio, crypto_list_instruments
Energy (free key)	Ember	energy_ember_series
Prediction Markets	Polymarket	polymarket_list_markets, polymarket_list_events, polymarket_get_market, polymarket_get_event, polymarket_price_history, polymarket_order_book, polymarket_midpoint, polymarket_last_trade_price, polymarket_spread
Prediction Markets	Kalshi	kalshi_list_markets, kalshi_get_market, kalshi_orderbook, kalshi_list_events, kalshi_get_event, kalshi_get_series, kalshi_trades, kalshi_exchange_status, kalshi_exchange_schedule, kalshi_list_series, kalshi_candlesticks
Prediction Markets	Manifold	manifold_search_markets, manifold_get_market, manifold_list_markets, manifold_get_user, manifold_market_positions, manifold_bets, manifold_groups, manifold_comments
News / Filings	SEC EDGAR	sec_company_filings, sec_company_facts, sec_company_concept, sec_full_text_search, sec_ticker_to_cik, sec_xbrl_frames
Macroeconomic	OECD	oecd_data, oecd_dataflows, oecd_data_structure
Macroeconomic	DBnomics (100+ sources)	dbnomics_search, dbnomics_series, dbnomics_providers, dbnomics_provider_datasets, dbnomics_dataset
Alternative (Flights)	OpenSky	flights_live_states, flights_by_aircraft, flights_by_airport, flights_track
Sentiment	Alternative.me	crypto_fear_greed_index
Congressional Trading	House/Senate Stock Watcher	congress_house_trades, congress_senate_trades

Optional keyed providers (register only when their key is set)

Category	Provider	Env	Tools
Macro / news	FRED	FRED_API_KEY	fred_series_observations, fred_series_info, fred_search_series, fred_releases
Stocks (real-time + fundamentals)	Finnhub	FINNHUB_API_KEY	finnhub_quote, finnhub_company_profile, finnhub_company_news, finnhub_basic_financials, finnhub_recommendation_trends, finnhub_insider_transactions, finnhub_earnings_surprises, finnhub_symbol_search
Commodities / Stocks / FX / Macro	Alpha Vantage	ALPHAVANTAGE_API_KEY	av_commodity, av_economic_indicator, av_time_series_daily, av_global_quote, av_fx_daily
Energy	EIA	EIA_API_KEY	eia_browse_route, eia_data
Congressional / lobbying / contracts	Quiver	QUIVER_API_KEY	quiver_congress_trading, quiver_lobbying, quiver_gov_contracts, quiver_insider_trading
Stocks (premium backup)	Tiingo	TIINGO_API_KEY	tiingo_eod_prices, tiingo_metadata, tiingo_iex_intraday
Energy	Ember	EMBER_API_KEY	energy_ember_series

Notes & caveats (verified live 2026-06-28; all return 200 from a US IP)

• Equities have two independent no-key backends. yahoo_* is primary; cboe_* (Cboe's delayed-quote CDN) is a fully independent fallback that also serves indices, full options chains, and ~20 years of daily history. Prefer cboe_* if Yahoo is throttled. tiingo_* adds a premium source with a free key.
• Crypto uses OKX, not Binance. Binance's fapi returns HTTP 451 to US IPs. OKX is no-key, US-accessible, and serves spot (BTC-USDT) and perpetual-swap futures (BTC-USDT-SWAP).
• Yahoo is unofficial and bot-sensitive: a full Chrome UA trips its bot filter (429), so the client sends a minimal Mozilla/5.0 and fails over query1 → query2. yahoo_quote_summary/yahoo_options_chain do the cookie+crumb handshake automatically.
• SEC EDGAR requires a descriptive User-Agent with a contact — set SEC_USER_AGENT.
• House Stock Watcher original S3 bucket and the first GitHub mirror both went away; this points at the current maintained mirror. Override via HOUSE_STOCK_WATCHER_URL / SENATE_STOCK_WATCHER_URL if it moves.
• OpenSky works anonymously (~400 credits/day); set OPENSKY_CLIENT_ID/SECRET for higher limits.
• The HTTP layer sends Accept-Language: en on every request — Node's undici defaults to Accept-Language: *, which made OECD's SDMX server 500.

Architecture (MCP best practices)

src/
  index.ts          # stdio entry point
  server.ts         # builds the server: instructions, annotations, structured
                    #   content, CHARACTER_LIMIT truncation, error mapping, catalog resource
  config.ts         # env-driven config (all optional)
  constants.ts      # CHARACTER_LIMIT, default page size
  lib/
    http.ts         # fetch wrapper: params, timeout, retries, formatHttpError
    cache.ts        # in-memory TTL cache
    tool.ts         # ToolDef + tool() helper (applies read-only annotations)
  providers/
    index.ts        # aggregates tools, uniqueness check, builds the catalog
    <provider>.ts   # one file per source; exports an array of ToolDef

• Annotations: every tool is readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true.
• Structured content: handlers return JSON; the server attaches structuredContent and truncates anything over CHARACTER_LIMIT (~25k chars) with a message telling the agent to narrow the query.
• Errors: mapped to actionable messages (404/403/429/451/5xx/timeout) and returned as MCP tool errors (isError: true), never thrown to the protocol.

Adding a provider: write src/providers/foo.ts exporting fooTools (array of tool({...})), then add it to PROVIDERS in src/providers/index.ts. See PROVIDERS.md for the full inventory and the key-required expansion roadmap.

A deliberate non-default

These are data APIs whose consumer is an LLM, so responses are compact JSON (no per-tool Markdown renderer) — optimized for agent context. structuredContent

• truncation cover the best-practice intent (context efficiency) without a lossy Markdown layer over numeric time series.