FMP Server

A Model Context Protocol server that provides financial data from Financial Modeling Prep for AI-assisted investment research.

Built with FastMCP 2.0 and Python.

Tools

Workflow Tools (start here)

High-level tools that orchestrate multiple API calls into single research-ready responses:

Tool	Description
stock_brief	Quick comprehensive snapshot: profile, price action, valuation, analyst consensus, insider signals, headlines
market_context	Full market environment: rates, yield curve, sector rotation, breadth, movers, economic calendar
earnings_setup	Pre-earnings positioning: consensus estimates, beat/miss history, analyst momentum, price drift, insider signals
earnings_preview	Pre-earnings setup scorecard: composite signal, thesis alignment, and bull/bear triggers
fair_value_estimate	Multi-method valuation: DCF, earnings-based, peer multiples, analyst targets, blended estimate
earnings_postmortem	Post-earnings synthesis: beat/miss, trend comparison, analyst reaction, market response, guidance tone

Atomic Tools (deeper dives)

Tool	Description
company_overview	Company profile, quote, key metrics, and analyst ratings
financial_statements	Income statement, balance sheet, cash flow (annual/quarterly)
analyst_consensus	Analyst grades, price targets, and forward estimates
price_history	Historical daily prices with technical context
stock_search	Search for stocks by name or ticker
insider_activity	Insider trading activity and transaction statistics
institutional_ownership	Top institutional holders and position changes
stock_news	Recent news and press releases
treasury_rates	Current Treasury yields and yield curve
economic_calendar	Upcoming economic events and releases
market_overview	Sector performance, gainers, losers, most active
earnings_transcript	Earnings call transcripts with pagination support
revenue_segments	Revenue breakdown by product and geography
peer_comparison	Peer group valuation and performance comparison
dividends_info	Dividend history, yield, growth, and payout analysis
earnings_calendar	Upcoming earnings dates with optional symbol filter
etf_lookup	ETF holdings or stock ETF exposure (dual-mode with auto-detect)
estimate_revisions	Analyst sentiment momentum: forward estimates, grade changes, beat rate
fmp_coverage_gaps	Docs parity introspection: endpoint families not yet implemented in this MCP server

Setup

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• An FMP API key

Install

uv sync

Configure

Set your API key as an environment variable:

export FMP_API_KEY=your_api_key_here

Or create a .env file:

FMP_API_KEY=your_api_key_here

Run

uv run fastmcp run server.py

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "fmp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fmp", "fastmcp", "run", "server.py"],
      "env": {
        "FMP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Testing

uv run pytest tests/ -v

All tools are tested with mocked API responses using respx.

Live e2e tests (real API) can be run in pooled parallel mode:

uv run pytest tests/test_live.py -m live_full -n 4 -q

Architecture

server.py          # FastMCP entry point, registers all tool modules
tools/_helpers.py  # Shared SDK helpers: safe calls, TTL cache, model dumping/normalization
tools/
  overview.py      # company_overview, stock_search
  financials.py    # financial_statements, revenue_segments
  valuation.py     # analyst_consensus, peer_comparison, estimate_revisions
  market.py        # price_history, dividends_info, earnings_calendar, etf_lookup
  ownership.py     # insider_activity, institutional_ownership
  news.py          # stock_news
  macro.py         # treasury_rates, economic_calendar, market_overview
  transcripts.py   # earnings_transcript (with pagination)
  workflows.py     # stock_brief, market_context, earnings_setup, earnings_preview, fair_value_estimate, earnings_postmortem

Key design decisions:

• Module pattern: Each tool file exports register(mcp, client) to keep tools organized
• SDK-first FMP client: Uses AsyncFMPDataClient (fmp-data==2.2.0) directly for typed endpoint coverage
• Parallel fetches: Workflow tools use asyncio.gather() to call multiple endpoints concurrently
• Graceful degradation: _safe_call() returns defaults on error so composite tools return partial data instead of failing entirely
• In-memory TTL cache: Avoids redundant API calls with configurable TTLs per data type (60s for quotes, 24h for profiles)

License

MIT