fmp-mcp

<div align="center"> # 🏦 FMP MCP Server ### The Ultimate Financial Data Bridge for AI **258 tools. One server. Every financial data point you'll ever need.** [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://nodejs.org/) [](LICENSE) [](https://financialmodelingprep.com/) <br/> [](https://github.com/simonpierreboucher02/fmp-mcp) [](https://github.com/simonpierreboucher02/fmp-mcp) [](https://github.com/simonpierreboucher02/fmp-mcp/issues) [](https://github.com/simonpierreboucher02/fmp-mcp/commits) [](https://github.com/simonpierreboucher02/fmp-mcp) [](https://github.com/simonpierreboucher02/fmp-mcp/graphs/contributors) --- **FMP MCP Server** transforms Claude into a Wall Street-grade financial analyst. Ask questions in natural language — get real-time market data, financial statements, analyst ratings, and more. [Getting Started](#-getting-started) • [All 258 Tools](#-all-258-tools-by-category) • [Usage Examples](#-usage-examples) • [Architecture](#-architecture) • [Authors](#-authors) </div> --- ## 🔥 What Is This? This is a **Model Context Protocol (MCP) server** that wraps the entire [Financial Modeling Prep API](https://financialmodelingprep.com/) — all **258 endpoints** — into tools that any MCP-compatible AI assistant can use. Once connected, your AI can: - 📊 Pull real-time stock quotes, forex rates, crypto prices - 📈 Analyze income statements, balance sheets, cash flows - 🎯 Get analyst ratings, price targets, and consensus grades - 🏛️ Track Senate & House trading activity - 🌍 Screen stocks across global markets with dozens of filters - 📰 Search financial news, press releases, earnings transcripts - 🔧 Compute technical indicators (SMA, EMA, RSI, MACD, ADX...) - 💰 Run DCF valuations and compare financial health scores - ...and **250+ more capabilities** --- ## ⚡ Quick Start ```bash # 1. Clone the repo git clone https://github.com/simonpierreboucher02/fmp-mcp.git cd fmp-mcp # 2. Install dependencies npm install # 3. Set your FMP API key echo "FMP_API_KEY=your_api_key_here" > .env # 4. Build npm run build # 5. You're ready! ``` > 🔑 Get your free API key at [financialmodelingprep.com](https://financialmodelingprep.com/developer/docs/) --- ## 🔌 Integration ### Claude Code (CLI) ```bash claude mcp add -e FMP_API_KEY=your_key -s user fmp -- node /path/to/fmp-mcp/dist/index.js ``` ### Claude Desktop Add to `~/.claude/claude_desktop_config.json`: ```json { "mcpServers": { "fmp": { "command": "node", "args": ["/path/to/fmp-mcp/dist/index.js"], "env": { "FMP_API_KEY": "your_api_key_here" } } } } ``` ### MCP Inspector (Testing) ```bash npx @modelcontextprotocol/inspector node dist/index.js ``` --- ## 💬 Usage Examples Once connected, just talk to your AI naturally: | You say... | Tool used | |---|---| | *"What's Apple's stock price right now?"* | `quote` | | *"Show me Tesla's income statement for the last 3 years"* | `income_statement` | | *"Who are the top gainers today?"* | `top_gainers` | | *"What's the RSI for NVDA on a daily timeframe?"* | `technical_rsi` | | *"Compare the P/E ratios across tech industry"* | `industry_pe_snapshot` | | *"What are senators trading right now?"* | `senate_latest` | | *"Give me the DCF valuation of Microsoft"* | `dcf` | | *"Find stocks with market cap over 100B in healthcare"* | `stock_screener` | | *"What's Bitcoin's price history this year?"* | `crypto_historical_full` | | *"Show me AAPL's earnings transcript Q4 2024"* | `earning_transcript` | --- ## 🛠 All 258 Tools by Category <details> <summary><b>🔍 Search & Discovery</b> — 18 tools</summary> | Tool | Description | |---|---| | `search_symbol` | Search stock ticker symbols across global markets | | `search_name` | Search by company or asset name | | `search_cik` | Look up CIK numbers for SEC filings | | `search_cusip` | Search by CUSIP number | | `search_isin` | Search by ISIN number | | `stock_screener` | Filter stocks by market cap, sector, country, beta, and more | | `search_exchange_variants` | Find all exchanges where a symbol is listed | | `stock_list` | Complete list of all stock symbols | | `financial_statement_list` | Companies with available financial statements | | `cik_list` | Database of SEC CIK numbers | | `symbol_changes` | Track symbol changes from mergers/splits | | `etf_list` | List all ETFs | | `actively_trading_list` | Currently trading instruments | | `earnings_transcript_list` | Companies with earnings transcripts | | `available_exchanges` | All supported exchanges | | `available_sectors` | All sectors | | `available_industries` | All industries | | `available_countries` | All countries | </details> <details> <summary><b>🏢 Company Data</b> — 17 tools</summary> | Tool | Description | |---|---| | `company_profile` | Full company profile: price, market cap, CEO, sector, description | | `company_profile_by_cik` | Profile lookup by CIK | | `company_notes` | Company-issued notes | | `stock_peers` | Peer companies in same sector/market cap | | `delisted_companies` | Delisted companies from US exchanges | | `employee_count` | Current workforce data | | `historical_employee_count` | Workforce evolution over time | | `market_capitalization` | Current market cap | | `batch_market_capitalization` | Market cap for multiple companies | | `historical_market_cap` | Historical market cap data | | `shares_float` | Share float and liquidity | | `all_shares_float` | Float data for all companies | | `mergers_acquisitions_latest` | Latest M&A activity | | `mergers_acquisitions_search` | Search M&A by company name | | `key_executives` | Company executives and compensation | | `executive_compensation` | Detailed exec compensation data | | `compensation_benchmark` | Industry compensation benchmarks | </details> <details> <summary><b>💹 Real-Time Quotes</b> — 16 tools</summary> | Tool | Description | |---|---| | `quote` | Full real-time stock quote | | `quote_short` | Quick quote snapshot | | `aftermarket_trade` | After-hours trade data | | `aftermarket_quote` | After-hours bid/ask quotes | | `stock_price_change` | Price changes across all timeframes | | `batch_quote` | Multiple stock quotes at once | | `batch_quote_short` | Multiple short quotes | | `batch_aftermarket_trade` | Batch after-hours trades | | `batch_aftermarket_quote` | Batch after-hours quotes | | `exchange_quotes` | All quotes for an exchange | | `mutual_fund_quotes` | All mutual fund quotes | | `etf_quotes` | All ETF quotes | | `commodity_quotes_batch` | All commodity quotes | | `crypto_quotes_batch` | All cryptocurrency quotes | | `forex_batch_quotes` | All forex pair quotes | | `index_quotes_batch` | All index quotes | </details> <details> <summary><b>📊 Financial Statements</b> — 27 tools</summary> | Tool | Description | |---|---| | `income_statement` | Income statement (annual/quarterly) | | `balance_sheet` | Balance sheet statement | | `cash_flow_statement` | Cash flow statement | | `latest_financial_statements` | Most recent filings across all companies | | `income_statement_ttm` | Trailing 12-month income statement | | `balance_sheet_ttm` | TTM balance sheet | | `cash_flow_statement_ttm` | TTM cash flow | | `key_metrics` | Key financial metrics | | `financial_ratios` | Profitability, liquidity, efficiency ratios | | `key_metrics_ttm` | TTM key metrics | | `ratios_ttm` | TTM financial ratios | | `financial_scores` | Altman Z-Score, Piotroski Score | | `owner_earnings` | Owner earnings (cash to shareholders) | | `enterprise_values` | Enterprise value (equity + debt) | | `income_statement_growth` | Revenue/profit growth over time | | `balance_sheet_growth` | Asset/liability growth | | `cash_flow_growth` | Cash flow growth trends | | `financial_growth` | Comprehensive growth metrics | | `financial_reports_dates` | Available report dates | | `financial_reports_json` | 10-K reports in JSON | | `financial_reports_xlsx` | 10-K reports in XLSX | | `revenue_product_segmentation` | Revenue by product line | | `revenue_geographic_segmentation` | Revenue by region | | `income_statement_as_reported` | As-reported income statement | | `balance_sheet_as_reported` | As-reported balance sheet | | `cash_flow_as_reported` | As-reported cash flow | | `full_financial_as_reported` | Complete as-reported financials | </details> <details> <summary><b>📈 Charts & Price History</b> — 10 tools</summary> | Tool | Description | |---|---| | `chart_light` | Basic EOD chart: date, price, volume | | `chart_full` | Full EOD chart: OHLCV, change, VWAP | | `chart_unadjusted` | Unadjusted for splits | | `chart_dividend_adjusted` | Dividend-adjusted prices | | `chart_intraday_1min` | 1-minute interval data | | `chart_intraday_5min` | 5-minute interval data | | `chart_intraday_15min` | 15-minute interval data | | `chart_intraday_30min` | 30-minute interval data | | `chart_intraday_1hour` | 1-hour interval data | | `chart_intraday_4hour` | 4-hour interval data | </details> <details> <summary><b>🌐 Economics</b> — 4 tools</summary> | Tool | Description | |---|---| | `treasury_rates` | Treasury rates for all maturities | | `economic_indicators` | GDP, CPI, unemployment, inflation | | `economic_calendar` | Upcoming economic data releases | | `market_risk_premium` | Market risk premium data | </details> <details> <summary><b>💰 Dividends, Earnings, IPOs & Splits</b> — 12 tools</summary> | Tool | Description | |---|---| | `dividends` | Company dividend history | | `dividends_calendar` | Upcoming dividend events | | `earnings` | Earnings reports with EPS estimates | | `earnings_calendar` | Upcoming earnings announcements | | `ipo_calendar` | Upcoming IPOs | | `ipo_disclosures` | IPO SEC disclosure filings | | `ipo_prospectus` | IPO prospectus details | | `stock_splits` | Stock split history | | `splits_calendar` | Upcoming stock splits | | `earning_transcripts_latest` | Latest earnings call transcripts | | `earning_transcript` | Full transcript by quarter | | `earning_transcript_dates` | Available transcript dates | </details> <details> <summary><b>📰 News</b> — 10 tools</summary> | Tool | Description | |---|---| | `fmp_articles` | FMP articles | | `general_news` | General financial news | | `press_releases_latest` | Latest press releases | | `stock_news_latest` | Latest stock news | | `crypto_news_latest` | Latest crypto news | | `forex_news_latest` | Latest forex news | | `press_releases_search` | Search press releases by symbol | | `stock_news_search` | Search stock news | | `crypto_news_search` | Search crypto news | | `forex_news_search` | Search forex news | </details> <details> <summary><b>🏛️ Institutional Ownership</b> — 8 tools</summary> | Tool | Description | |---|---| | `institutional_ownership_latest` | Latest ownership filings | | `sec_filings_extract` | Extract SEC filing data | | `form_13f_dates` | Form 13F filing dates | | `filings_analytics_by_holder` | Analytics by institutional holder | | `holder_performance_summary` | Holder performance metrics | | `holder_industry_breakdown` | Holder industry allocation | | `positions_summary` | Institutional positions for a stock | | `industry_ownership_summary` | Industry-level ownership data | </details> <details> <summary><b>🎯 Analyst Ratings</b> — 8 tools</summary> | Tool | Description | |---|---| | `analyst_estimates` | Revenue & EPS forecasts | | `ratings_snapshot` | Financial ratings snapshot | | `historical_ratings` | Historical ratings | | `price_target_summary` | Average price targets | | `price_target_consensus` | Consensus price targets | | `grades` | Latest analyst grades | | `grades_historical` | Historical grade changes | | `grades_consensus` | Buy/Hold/Sell summary | </details> <details> <summary><b>📉 Market Performance</b> — 11 tools</summary> | Tool | Description | |---|---| | `sector_performance_snapshot` | Sector performance | | `industry_performance_snapshot` | Industry performance | | `historical_sector_performance` | Historical sector data | | `historical_industry_performance` | Historical industry data | | `sector_pe_snapshot` | Sector P/E ratios | | `industry_pe_snapshot` | Industry P/E ratios | | `historical_sector_pe` | Historical sector P/E | | `historical_industry_pe` | Historical industry P/E | | `top_gainers` | Biggest stock gainers | | `top_losers` | Biggest stock losers | | `most_active` | Most actively traded stocks | </details> <details> <summary><b>🔧 Technical Indicators</b> — 9 tools</summary> | Tool | Description | |---|---| | `technical_sma` | Simple Moving Average | | `technical_ema` | Exponential Moving Average | | `technical_wma` | Weighted Moving Average | | `technical_dema` | Double Exponential Moving Average | | `technical_tema` | Triple Exponential Moving Average | | `technical_rsi` | Relative Strength Index | | `technical_stddev` | Standard Deviation | | `technical_williams` | Williams %R | | `technical_adx` | Average Directional Index | </details> <details> <summary><b>📦 ETF & Funds</b> — 9 tools</summary> | Tool | Description | |---|---| | `etf_holdings` | ETF asset holdings breakdown | | `etf_info` | ETF/fund information | | `etf_country_allocation` | Country allocation | | `etf_asset_exposure` | Which ETFs hold a stock | | `etf_sector_weighting` | Sector allocation | | `fund_disclosure_latest` | Latest fund disclosures | | `fund_disclosure` | Fund disclosure by quarter | | `fund_disclosure_search` | Search fund disclosures | | `fund_disclosure_dates` | Available disclosure dates | </details> <details> <summary><b>📋 SEC Filings</b> — 12 tools</summary> | Tool | Description | |---|---| | `sec_filings_8k` | Latest 8-K filings | | `sec_filings_latest` | Latest SEC filings | | `sec_filings_by_form_type` | Search by form type | | `sec_filings_by_symbol` | Search by stock symbol | | `sec_filings_by_cik` | Search by CIK | | `sec_filings_by_name` | Search by company name | | `sec_company_search_symbol` | Company search by symbol | | `sec_company_search_cik` | Company search by CIK | | `sec_company_profile` | Full SEC company profile | | `industry_classification_list` | SIC code list | | `industry_classification_search` | Search SIC codes | | `all_industry_classification` | All industry classifications | </details> <details> <summary><b>🕵️ Insider Trading</b> — 6 tools</summary> | Tool | Description | |---|---| | `insider_trading_latest` | Latest insider trades | | `insider_trading_search` | Search insider trades | | `insider_trading_by_name` | Search by person name | | `insider_transaction_types` | Transaction type list | | `insider_trade_statistics` | Trade statistics by company | | `acquisition_ownership` | Acquisition ownership changes | </details> <details> <summary><b>📊 Market Indexes</b> — 14 tools</summary> | Tool | Description | |---|---| | `index_list` | All global market indexes | | `index_quote` | Real-time index quote | | `index_quote_short` | Quick index snapshot | | `index_historical_light` | Historical index prices (light) | | `index_historical_full` | Historical index prices (full) | | `index_intraday_1min` | 1-min intraday index data | | `index_intraday_5min` | 5-min intraday index data | | `index_intraday_1hour` | 1-hour intraday index data | | `sp500_constituents` | S&P 500 companies | | `nasdaq_constituents` | Nasdaq companies | | `dowjones_constituents` | Dow Jones companies | | `historical_sp500` | Historical S&P 500 changes | | `historical_nasdaq` | Historical Nasdaq changes | | `historical_dowjones` | Historical Dow Jones changes | </details> <details> <summary><b>🕐 Market Hours</b> — 3 tools</summary> | Tool | Description | |---|---| | `exchange_market_hours` | Trading hours for an exchange | | `holidays_by_exchange` | Exchange holiday schedule | | `all_exchange_market_hours` | All exchange hours | </details> <details> <summary><b>🛢️ Commodities</b> — 8 tools</summary> | Tool | Description | |---|---| | `commodities_list` | All tracked commodities | | `commodity_quote` | Real-time commodity quote | | `commodity_quote_short` | Quick commodity snapshot | | `commodity_historical_light` | Historical commodity prices (light) | | `commodity_historical_full` | Historical commodity prices (full) | | `commodity_intraday_1min` | 1-min intraday commodity data | | `commodity_intraday_5min` | 5-min intraday commodity data | | `commodity_intraday_1hour` | 1-hour intraday commodity data | </details> <details> <summary><b>💎 Valuation</b> — 4 tools</summary> | Tool | Description | |---|---| | `dcf` | Discounted Cash Flow valuation | | `levered_dcf` | Levered DCF (with debt impact) | | `custom_dcf` | Custom DCF with tailored assumptions | | `custom_levered_dcf` | Custom levered DCF analysis | </details> <details> <summary><b>💱 Forex</b> — 8 tools</summary> | Tool | Description | |---|---| | `forex_list` | All currency pairs | | `forex_quote` | Real-time forex quote | | `forex_quote_short` | Quick forex snapshot | | `forex_historical_light` | Historical forex prices (light) | | `forex_historical_full` | Historical forex prices (full) | | `forex_intraday_1min` | 1-min intraday forex data | | `forex_intraday_5min` | 5-min intraday forex data | | `forex_intraday_1hour` | 1-hour intraday forex data | </details> <details> <summary><b>🪙 Crypto</b> — 8 tools</summary> | Tool | Description | |---|---| | `crypto_list` | All cryptocurrencies | | `crypto_quote` | Real-time crypto quote | | `crypto_quote_short` | Quick crypto snapshot | | `crypto_historical_light` | Historical crypto prices (light) | | `crypto_historical_full` | Historical crypto prices (full) | | `crypto_intraday_1min` | 1-min intraday crypto data | | `crypto_intraday_5min` | 5-min intraday crypto data | | `crypto_intraday_1hour` | 1-hour intraday crypto data | </details> <details> <summary><b>🏛️ Government Trading</b> — 6 tools</summary> | Tool | Description | |---|---| | `senate_latest` | Latest Senate financial disclosures | | `house_latest` | Latest House financial disclosures | | `senate_trades` | Senate trading by stock | | `senate_trades_by_name` | Senate trading by senator name | | `house_trades` | House trading by stock | | `house_trades_by_name` | House trading by representative name | </details> <details> <summary><b>🌱 ESG</b> — 3 tools</summary> | Tool | Description | |---|---| | `esg_disclosures` | ESG disclosure data | | `esg_ratings` | ESG ratings | | `esg_benchmark` | ESG benchmark comparison | </details> <details> <summary><b>📑 COT Reports</b> — 3 tools</summary> | Tool | Description | |---|---| | `cot_report` | Commitment of Traders report | | `cot_analysis` | COT report analysis | | `cot_list` | Available COT reports list | </details> <details> <summary><b>🚀 Crowdfunding & Equity Offerings</b> — 6 tools</summary> | Tool | Description | |---|---| | `crowdfunding_latest` | Latest crowdfunding campaigns | | `crowdfunding_search` | Search crowdfunding campaigns | | `crowdfunding_by_cik` | Crowdfunding by company CIK | | `equity_offerings_latest` | Latest equity offerings | | `equity_offerings_search` | Search equity offerings | | `equity_offerings_by_cik` | Equity offerings by CIK | </details> <details> <summary><b>📦 Bulk Data</b> — 18 tools</summary> | Tool | Description | |---|---| | `bulk_profiles` | Bulk company profiles | | `bulk_ratings` | Bulk financial ratings | | `bulk_dcf` | Bulk DCF valuations | | `bulk_scores` | Bulk financial scores | | `bulk_price_target_summary` | Bulk price targets | | `bulk_etf_holders` | Bulk ETF holders | | `bulk_upgrades_downgrades` | Bulk analyst consensus | | `bulk_key_metrics_ttm` | Bulk TTM key metrics | | `bulk_ratios_ttm` | Bulk TTM ratios | | `bulk_stock_peers` | Bulk stock peers | | `bulk_earnings_surprises` | Bulk earnings surprises | | `bulk_income_statement` | Bulk income statements | | `bulk_income_statement_growth` | Bulk income growth | | `bulk_balance_sheet` | Bulk balance sheets | | `bulk_balance_sheet_growth` | Bulk balance sheet growth | | `bulk_cash_flow` | Bulk cash flow statements | | `bulk_cash_flow_growth` | Bulk cash flow growth | | `bulk_eod` | Bulk end-of-day prices | </details> --- ## 🏗 Architecture ``` fmp-mcp/ ├── src/ │ ├── index.ts → MCP Server entry point (stdio transport) │ ├── api/ │ │ └── client.ts → FMP API HTTP client + error handling │ └── tools/ │ ├── index.ts → Barrel file: registers all 258 tools │ ├── search.ts → 🔍 Search & Discovery (18) │ ├── company.ts → 🏢 Company Data (17) │ ├── quotes.ts → 💹 Quotes (16) │ ├── financials.ts → 📊 Financial Statements (27) │ ├── charts.ts → 📈 Charts & Price History (10) │ ├── economics.ts → 🌐 Economics (4) │ ├── dividends_earnings.ts → 💰 Dividends & Earnings (12) │ ├── news.ts → 📰 News (10) │ ├── institutional.ts → 🏛️ Institutional Ownership (8) │ ├── analyst.ts → 🎯 Analyst Ratings (8) │ ├── market_performance.ts → 📉 Market Performance (11) │ ├── technical.ts → 🔧 Technical Indicators (9) │ ├── etf_funds.ts → 📦 ETF & Funds (9) │ ├── sec_filings.ts → 📋 SEC Filings (12) │ ├── insider_trading.ts → 🕵️ Insider Trading (6) │ ├── indexes.ts → 📊 Market Indexes (14) │ ├── market_hours.ts → 🕐 Market Hours (3) │ ├── commodities.ts → 🛢️ Commodities (8) │ ├── valuation.ts → 💎 Valuation (4) │ ├── forex.ts → 💱 Forex (8) │ ├── crypto.ts → 🪙 Crypto (8) │ ├── government.ts → 🏛️ Government Trading (6) │ ├── esg.ts → 🌱 ESG (3) │ ├── cot.ts → 📑 COT Reports (3) │ ├── crowdfunding.ts → 🚀 Crowdfunding (6) │ └── bulk.ts → 📦 Bulk Data (18) ├── package.json ├── tsconfig.json └── .env → FMP_API_KEY ``` ### Design Principles - **`fmpRequest(path, params)`** — Single shared HTTP client. Auto-appends API key, filters `undefined` params, handles FMP error responses. - **`createToolHandler(path)`** — DRY factory. Wraps every tool in try/catch + JSON formatting. Each tool definition is ~5 lines. - **Zod validation** — Every tool has typed input schemas with descriptions, so the AI knows exactly what parameters are available. - **Modular by category** — 26 files, each self-contained. Easy to maintain, extend, or contribute to. --- ## 📋 Requirements | Requirement | Version | |---|---| | Node.js | >= 18.0 | | npm | >= 9.0 | | FMP API Key | [Get one here](https://financialmodelingprep.com/developer/docs/) | --- ## 🧪 Development ```bash # Run in dev mode (no build step) npm run dev # Build for production npm run build # Start production server npm start # Test with MCP Inspector npx @modelcontextprotocol/inspector node dist/index.js ``` --- ## 🤝 Contributing Contributions are welcome! Here's how: 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## 📄 License This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. --- ## ✍️ Authors <table> <tr> <td align="center"> <b>Simon-Pierre Boucher</b><br/> _{Creator & Lead Developer}<br/><br/> <a href="mailto:spbou4@protonmail.com">spbou4@protonmail.com</a><br/> <a href="https://www.spboucher.ai">www.spboucher.ai</a><br/><br/> <a href="https://github.com/simonpierreboucher02"> <img src="https://img.shields.io/badge/GitHub-simonpierreboucher02-181717?style=flat-square&logo=github" alt="GitHub"/> </a> </td> <td align="center"> <b>Claude (Anthropic)</b><br/> _{Co-Author & AI Architect}<br/><br/> Built with Claude Opus 4.6<br/> via Claude Code CLI<br/><br/> <a href="https://claude.ai"> <img src="https://img.shields.io/badge/Anthropic-Claude-blueviolet?style=flat-square" alt="Claude"/> </a> </td> </tr> </table> --- <div align="center"> **Built with Claude Code** — the AI-powered development tool by Anthropic [](https://claude.ai/claude-code) *Turning 258 API endpoints into natural conversations since 2025.* </div>