fmp-mcp

Financial intelligence for your AI agent — powered by live market data.

Give Claude (or any MCP-compatible AI) the ability to analyze stocks, screen markets, compare peers, read earnings calls, and track sector rotations — all grounded in real financial data from Financial Modeling Prep.

This isn't a raw API wrapper. Each tool is purpose-built for a specific analytical task, composing multiple data sources into structured, analysis-ready outputs designed for AI consumption.

Tool surface below was verified against fmp/server.py on 2026-04-30. The repo build exposes 20 MCP tools; the two estimate-revision tools require the estimates extra plus database access for useful live results.

What your AI can do

Market Intelligence

• get_market_context — One-call market snapshot: indices, sectors, gainers/losers, economic events
• get_sector_overview — Sector and industry performance with P/E valuations
• get_news — Stock-specific or broad market news
• get_events_calendar — Earnings, dividends, splits, and IPO calendars
• get_economic_data — Economic indicators and high-impact event tracking

Fundamental Analysis

• fmp_fetch — Direct access to 60+ financial data endpoints (income statements, balance sheets, cash flows, key metrics, and more)
• fmp_market_cap_check — Compare current market cap against the latest annual filing value
• compare_peers — Side-by-side peer comparison across 12 financial ratios
• get_earnings_transcript — Parsed earnings calls with speaker attribution and Q&A sections

Stock Screening & Discovery

• screen_stocks — Screen by sector, market cap, beta, dividend, volume, and more
• get_institutional_ownership — Institutional holder analytics and ownership trends
• get_insider_trades — Insider transaction flow and statistics
• get_etf_holdings — ETF/fund holdings, sector and country allocation

Technical Analysis

• get_technical_analysis — Composite signals from 7 indicators (SMA, EMA, RSI, MACD, Bollinger, ADX, Williams %R) with buy/sell scoring

Analyst Sentiment

• get_estimate_revisions — Historical EPS/revenue estimate revision trends
• screen_estimate_revisions — Screen for estimate momentum across a universe of stocks

Data Discovery

• fmp_list_endpoints — Browse all 60+ available data endpoints by category
• fmp_describe — Get parameter documentation for any endpoint
• fmp_search — Search for companies by name or ticker
• fmp_profile — Company profile with sector, industry, and key stats

Install

pip install fmp-mcp

Optional local estimate storage (requires PostgreSQL; hosted MCP reads do not):

pip install "fmp-mcp[estimates]"

Configuration

Set your API key:

export FMP_API_KEY="your_key"

Optional settings:

• FMP_CACHE_DIR — Custom cache directory (default: ~/.cache/fmp-mcp/)
• FMP_CACHE_MAXSIZE — Max in-memory cache entries (default: 200)

Application integration

The installed fmp-mcp distribution owns the fmp import. It does not search for a Risk checkout, load a checkout .env, or import application policy. The source package lives at Risk's fmp-mcp/. Install it from the Risk root with the single editable list, .venv/bin/python -m pip install --no-deps -r requirements-local.txt, which also installs brokerage-connect. Dev tools come from requirements-dev.txt.

Applications must explicitly configure the client once at startup before any network fetch. An unconfigured client refuses dispatch and names the required configure_client(...) call. Applications can bind these callbacks:

• fmp.client.configure_client(budget_guard=..., event_observer=...).

The guard accepts fn, args, kwargs plus provider/operation/budget metadata. The observer receives (event, endpoint, **details), where event is success (duration_ms, status), rate_limit, error (error), plan_limit (error), or cache_hit (params). Explicit configure_client() selects the public default: fmp.spend writes one machine-wide API spend-ledger row per network call and a zero-call cache_hit row per cache-answered request (hank-model-authority), refuses a call whose spend ceiling is already met with SpendCeilingExceeded, and rate limits and errors go to native Python logging. A host that passes its own budget_guard owns metering and nothing in fmp.spend runs. The public fmp-mcp / python -m fmp.server entrypoint selects the default policy before serving tools.

• `fmp.tools.peers.configure_peer_tools(metric_resolver=..., peer_discovery=...,

spot_fx_rate=...). Metric resolvers return the existing structural peers/source/to_dict() result; discovery returns ticker strings. Expected policy failures raise PeerSelectionError. Standalone discovery uses FMP stock_peers; metric-context selection without application policy asks for explicit peers. Standalone non-USD conversion reads the latest daily close of FMP's <currency>USD` pair. The optional FX callback returns a currency-to-USD rate.

Risk process entrypoints call fmp_runtime.configure() after environment hydration to bind all five callbacks; logging, billing, peer selection, and exchange-mapping policy remain application code. bootstrap_env.bootstrap() only hydrates environment and never imports FMP or application policy. scripts/run_fmp_server.py owns Risk credential hydration and policy setup before invoking the installed fmp.server.run() (which preserves the caller's policy). Risk-only wrappers live in utils/fmp_compat.py and utils/fmp_fx.py, and the local collector lives in scripts/snapshot_estimates.py.

The source retains the Hank-only transcript_kpi_fetcher.py and manifest_source_dispatcher.py; public distribution sync excludes them. Their application consumers require the separately installed named industry and value-semantics libraries. Sync copies source bytes without vendoring or rewriting imports.

Run

fmp-mcp

Or register the installed package with Claude Code from any directory:

claude mcp add fmp-mcp --scope user \
  -- python3 -m fmp.server

You can also use a generic MCP config:

{
  "mcpServers": {
    "fmp-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fmp-mcp"],
      "env": { "FMP_API_KEY": "your_key" }
    }
  }
}

How it's different

Requirements

• Python 3.11+
• FMP API key (get one here)

Related Docs

• docs/reference/FMP_ENDPOINTS.md — registered endpoint catalog
• docs/reference/MCP_SERVERS.md — server registration and troubleshooting