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.

Related MCP server: Finance MCP Server

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

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

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.