Metadata-Version: 2.5
Name: finzdata-mcp
Version: 0.1.5
Summary: FinzData MCP server: point-in-time market data for AI agents. US stocks incl. delisted, ETFs, ticks, futures, options gamma (GEX), crypto, FX, indexes, COT, 13F, fundamentals, 22,700+ macro series and backtests.
Project-URL: Homepage, https://finzdata.com
Project-URL: Pricing, https://finzdata.com/pricing
Project-URL: Repository, https://github.com/FinzData/finzdata-mcp
Author-email: FinzData <info@finzdata.com>
License: MIT
License-File: LICENSE
Keywords: cot,financial data,fred,historical stock data,intraday,market data,mcp,stock api
Requires-Python: >=3.10
Requires-Dist: certifi
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

<p align="center"><a href="https://finzdata.com"><img src="https://finzdata.com/assets/brand/finzdata-logo-full.png" alt="FinzData" width="360"></a></p>

# FinzData MCP server

<!-- mcp-name: io.github.FinzData/finzdata-mcp -->

Research-grade US market data and server-side backtests for AI agents: Claude, ChatGPT, Gemini CLI, Cursor, Kimi, GLM and any MCP client.

**Remote server:** `https://api.finzdata.com/mcp` (Streamable HTTP, MCP 2026-07-28, accepts 2025-06-18 clients)
**Auth:** OAuth 2.1 with PKCE (sign in with your FinzData API key), or the header `Authorization: Bearer YOUR_API_KEY`
**Free key:** https://finzdata.com/signin · Pricing: https://finzdata.com/shop · Agent docs: https://api.finzdata.com/agents.md

## Coverage

Market data your backtests can trust. The whole market, remembered: every one of the 16,000+ US stocks that has traded on the NYSE and Nasdaq in the last 26+ years, delisted included, point in time. Around them: 139 futures markets with every contract since 2007, the VIX and Cboe volatility indexes with the VIX futures curve, options-market gamma (GEX) for 11,200+ stocks, ETFs and indexes since 2010 plus end-of-day options chains, 5,100+ ETFs, 74 crypto pairs (Bitcoin since 2013), 79 FX pairs and 123 indexes. Macro exactly as it was known: 22,700+ series including CPI, payrolls, wages, GDP and the Treasury yield curve, every vintage kept. Plus COT positioning since 1986, 13F holdings, insider trades, short interest, congressional trades, election spending and Global Macro Pulse (shipping, ports, air and road traffic). Bars at every resolution you backtest on: 1-minute, 5-minute, 15-minute, 30-minute, hourly and daily, and tick-level trades for 1,100+ stocks and ETFs. In pandas with one line: `pip install finzdata`.

## Why FinzData for agents

- **Survivorship-free.** Universes include every company that traded on a date, delisted names included.
- **Point-in-time.** Every data tool takes `as_of`, so answers contain only what was public that day: fundamentals as filed, and macro series as first published (ALFRED vintages).
- **Backtests run on the server.** Describe a strategy and get back CAGR, volatility, Sharpe, drawdown, turnover, a benchmark, an equity curve, a reproducible `run_id` and a deflated Sharpe ratio that counts every variant you tried.

## Tools (all read-only)

| Tool | What it returns |
|---|---|
| `search_datasets` / `describe_dataset` | The catalog, fields and coverage |
| `get_universe` | Every US symbol trading on a date, or the 500/1000/3000 most-traded |
| `get_bars` | Daily and intraday OHLCV (1, 5, 15, 30-minute, hourly), split-adjusted |
| `get_fundamentals_pit` | Valuation and fundamentals as known on a date (P/E, EV/EBITDA, revenue, debt…) |
| `get_macro_vintage` | FRED/ALFRED series exactly as published by a date |
| `get_cot` | CFTC Commitments of Traders positioning |
| `get_13f` | Institutional holdings from 13F filings |
| `get_events` | Earnings dates, splits and economic releases |
| `backtest_export` | Daily bars as ready-to-load files for backtrader, backtesting.py, vectorbt, zipline, QuantConnect LEAN, NautilusTrader, freqtrade or qlib |
| `run_backtest` | Momentum, MA cross, factor or formula strategies, long-only or long/short |
| `compare_runs` | Several backtests side by side |

## Connect

**Claude:** add FinzData from the Claude connector directory, or add a custom connector with `https://api.finzdata.com/mcp`.

**ChatGPT:** add the FinzData app from the ChatGPT directory, or add a connector in developer mode with the URL above.

**Gemini CLI:**
```bash
export FINZDATA_API_KEY=your-key
gemini extensions install https://github.com/FinzData/finzdata-mcp
```

**Cursor** (`.cursor/mcp.json`), **Windsurf, Cline, Kimi CLI, GLM / Z.ai coding tools and any client that takes a remote server:**
```json
{
  "mcpServers": {
    "finzdata": {
      "url": "https://api.finzdata.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

**Clients that only run local (stdio) servers:** `pip install finzdata-mcp` (or `uvx finzdata-mcp`) with `FINZDATA_API_KEY` set. See [README.pypi.md](README.pypi.md).

## Example prompts

- "Backtest 12-1 momentum on the 500 most-traded US stocks since 2010, monthly, top 50, 10 bps costs."
- "What was the US unemployment rate for March 2020 as first reported?"
- "How are managed-money traders positioned in gold futures?"
- "Which institutions hold the most NVIDIA shares in the latest 13F quarter?"

## Plans

Free accounts cover the last 12 months, with 1,000 data calls and 5 backtests a day. Paid plans and prepaid credits ($0.001 per data call, $0.05 per backtest) unlock full history.

Data, not investment advice. Support: info@finzdata.com · https://finzdata.com/support · Privacy: https://finzdata.com/privacy
