# Fmp Mcp Server > Financial Modeling Prep MCP Server - **Type:** MCP server - **Install:** `agentstack add mcp-cdtait-fmp-mcp-server` - **Verified:** Pending review - **Seller:** [cdtait](https://agentstack.voostack.com/s/cdtait) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [cdtait](https://github.com/cdtait) - **Source:** https://github.com/cdtait/fmp-mcp-server - **Website:** https://github.com/cdtait/fmp-mcp-server ## Install ```sh agentstack add mcp-cdtait-fmp-mcp-server ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Financial Modeling Prep MCP Server A Model Context Protocol (MCP) server that provides tools, resources, and prompts for financial analysis using the Financial Modeling Prep API. ## Features - **Company Information**: Access detailed company profiles and peer comparisons - **Financial Statements**: Retrieve and analyze income statements, balance sheets, and cash flow statements - **Financial Metrics**: Access key financial ratios and metrics for investment analysis - **Market Data**: Get market snapshots, indexes, and news - **Stock Quotes**: Get current stock quotes, aftermarket quotes, and simplified price information - **Stock Charts**: Access historical price data and calculate price changes - **Analyst Ratings**: Get analyst recommendations and rating details - **Market Indices**: Access market indices data and quotes - **Market Performers**: Get biggest gainers, losers, and most active stocks - **Market Hours**: Check market hours and holidays for major exchanges - **ETF Analysis**: Analyze ETF sector weightings, country exposure, and holdings - **Commodities**: Get commodities list, current prices, and historical price data - **Cryptocurrencies**: Access cryptocurrency listings and current quotes - **Forex**: Get forex pair listings and exchange rates - **Technical Indicators**: Calculate and interpret Exponential Moving Average (EMA) - **Analysis Prompts**: Generate investment analyses using predefined prompt templates - **Chat Agent**: Interactive CLI chat interface to FMP MCP Server - **Multiple Transport Options**: Support for stdio, SSE, and Streamable HTTP transports - **Stateful & Stateless Modes**: Flexible deployment options for different use cases - **Docker Support**: Containerized deployment with configurable transport modes - **Health Check Endpoint**: Built-in `/health` endpoint for load balancer health checks ## Code Organization The codebase is organized to align with the FMP API documentation structure found at [FMP API Documentation](https://site.financialmodelingprep.com/developer/docs/stable). Each module corresponds to a specific section of the API: - **analyst.py**: Analyst recommendations and price targets - **charts.py**: Stock chart and historical price data - **commodities.py**: Commodities list, price data, and historical price data - **company.py**: Company profile and related information - **crypto.py**: Cryptocurrency listings and quotes - **etf.py**: ETF sector weightings, country exposure, and holdings - **forex.py**: Forex pair listings and exchange rates - **indices.py**: Market indices listings and quotes - **market.py**: Market data and news - **market_hours.py**: Market hours and holidays for major exchanges - **market_performers.py**: Biggest gainers, losers, and most active stocks - **quote.py**: Stock quote data, aftermarket quotes, and price changes - **search.py**: API for searching tickers and companies - **statements.py**: Financial statements (income, balance sheet, cash flow, ratios) - **technical_indicators.py**: Technical indicators and analysis ### API Endpoint Standardization The codebase uses a standardized approach for retrieving quotes across different asset types: - The unified **quote** endpoint is used for retrieving quotes for all asset types, including: - Stocks - Forex pairs - Cryptocurrencies - Commodities - Market indices - Each module provides specialized formatting for its respective asset type: - **get_quote**: Standard stock quotes - **get_aftermarket_quote**: Aftermarket trading quotes with bid/ask data - **get_forex_quotes**: Currency exchange rates - **get_crypto_quote**: Cryptocurrency prices - **get_commodities_prices**: Commodity prices - **get_historical_price_eod_light**: Historical commodity price data - **get_index_quote**: Market index values This standardization improves code maintainability and provides a consistent approach to retrieving asset prices throughout the application. ### Other Recent Changes - **get_aftermarket_quote**: Added new function for retrieving aftermarket trading data - Uses the "aftermarket-quote" endpoint to get bid/ask prices and sizes - Includes trading volume and timestamp information - Formats timestamps from milliseconds to human-readable format - Provides structured Markdown output with emoji indicators - **get_historical_price_eod_light**: Added new function for retrieving historical commodity price data - Uses the "historical-price-eod/light" endpoint for efficient data retrieval - Supports date range filtering with from_date and to_date parameters - Includes limit parameter for controlling the number of results - Calculates daily price changes and percentage changes between consecutive days - Displays data in a well-formatted Markdown table with emoji indicators (🔺, 🔻, ➖) for price movements ### Earlier Changes - **get_quote_change**: Updated to use the "stock-price-change" endpoint instead of "quote-change" endpoint - Now returns price changes for all time periods (1D, 5D, 1M, 3M, 6M, YTD, 1Y, 3Y, 5Y, 10Y, max) in a single request - Improved table formatting for better readability - Emoji indicators (🔺, 🔻, ➖) for clearer trend visualization - **get_financial_estimates**: Updated to match the actual "analyst-estimates" endpoint structure - Added support for all fields in API response (revenueAvg, revenueHigh, revenueLow, etc.) - Added pagination support with new page parameter - Improved presentation with analyst count information - Enhanced display of high/low/average values for all metrics - **get_price_target_news**: Improved to use the "price-target-news" endpoint - Added support for filtering by symbol - Includes adjusted price target information - Better date formatting for improved readability - Support for all fields in the API response - **get_key_metrics**: Enhanced comprehensive financial metrics tool - Improved support for all metrics from the key-metrics endpoint - Added detailed categorization of metrics (valuation, profitability, liquidity, etc.) - Better formatting and organization of financial data - Support for fiscal year and currency information Tests are similarly organized with one test file per module, following a consistent pattern to ensure comprehensive coverage. ## Installation 1. Clone the repository: ```bash git clone https://github.com/cdtait/fmp-mcp-server.git cd fmp-mcp-server ``` 2. Set up the environment using either pip or [uv](https://github.com/astral-sh/uv): ### Option 1: Using pip (Standard) ```bash # Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install pip if not available (rare but possible in some environments) # curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && python get-pip.py # Install dependencies python -m pip install -r requirements.txt # For development (includes testing dependencies) python -m pip install -e ".[dev]" ``` ### Option 2: Using uv (Faster) ```bash # Install uv if you don't have it yet curl -LsSf https://astral.sh/uv/install.sh | sh export PATH=~/.local/bin/:${PATH} # Create and activate the environment uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies uv pip install -r requirements.txt # For development (includes testing dependencies) uv pip install -e ".[dev]" ``` 3. Set up your Financial Modeling Prep API key: ```bash # Copy the template cp .env.template .env # Edit the .env file to add your API key # Replace 'your_api_key_here' with your actual API key from FMP ``` You can get an API key by registering at [Financial Modeling Prep](https://site.financialmodelingprep.com/developer/docs/). 4. Set up your OpenAI API key (if using the chat agent): ```bash # Add your OpenAI API key to the .env file echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env ``` 5. Verify installation with tests: ```bash # Run unit tests python -m pytest tests/ -v # Run acceptance tests with mock data TEST_MODE=true python -m pytest tests/acceptance_tests.py -v ``` ## Development This project follows a Test-Driven Development (TDD) approach. The test suite is organized in the `tests/` directory. ### Testing Strategy The project implements a comprehensive testing strategy with three distinct test types: 1. **Unit Tests** (`test_company.py`, `test_quotes.py`, etc.) - Focus on testing individual functions in isolation - Organized by module to match the code structure - Mock all external dependencies - Verify correct behavior for normal operation, edge cases, and error handling - Fast execution and no external dependencies - Follow consistent pattern with @patch decorator for mocking - Import functions after patching to ensure proper mocking isolation 2. **Integration Tests** (`test_server.py`, `test_resources.py`) - Test how components work together - Verify proper server setup, tool registration, and resource handling - Test end-to-end flows with mocked external APIs - Ensure system components integrate correctly - Validate proper error handling between components 3. **Acceptance Tests** (`acceptance_tests.py`) - Validate integration with the real FMP API - Verify API connectivity and response formats - Test error handling with invalid inputs - Focus on data structure rather than specific values - Can run in both real API mode or with mock data using TEST_MODE=true - Only run with real API when explicitly triggered or when an API key is provided This multi-level approach provides confidence in both individual components and the system as a whole, ensuring that the application works correctly in isolation and when integrated with the real API. ### Running Tests ```bash # Run all unit and integration tests python -m pytest # Run with coverage report python -m pytest --cov=src tests/ # Run specific test file python -m pytest tests/test_company.py # Run tests with specific marker python -m pytest -m acceptance ``` #### Acceptance Tests The project includes acceptance tests that validate integration with the real FMP API. These tests require a valid API key and can also run with mock data. To run acceptance tests: ```bash # Option 1: Run with the real API # Set your API key export FMP_API_KEY=your_api_key_here # Run the acceptance tests with real API python -m pytest tests/acceptance_tests.py -v # Option 2: Run with mock data # This doesn't require an API key and uses mock responses TEST_MODE=true python -m pytest tests/acceptance_tests.py -v ``` These tests verify: - API connectivity - Data format and structure - Error handling with invalid inputs - Tool formatting with real data The acceptance tests are designed to check format and structure without asserting specific values that may change over time (like stock prices). This makes them suitable for CI/CD pipelines with a valid API key secret. Using TEST_MODE=true enables running the acceptance tests in CI environments without requiring a real API key, using the mock responses defined in conftest.py. ### Project Structure ``` fmp-mcp-server/ ├── src/ # Source code │ ├── api/ # API client functionality │ │ ├── client.py # FMP API client │ ├── tools/ # MCP tools implementation │ │ ├── analyst.py # Analyst ratings tools │ │ ├── charts.py # Stock chart tools │ │ ├── commodities.py # Commodities tools │ │ ├── company.py # Company profile tools │ │ ├── crypto.py # Cryptocurrency tools │ │ ├── etf.py # ETF analysis tools │ │ ├── forex.py # Forex tools │ │ ├── indices.py # Market indices tools │ │ ├── market.py # Market data tools │ │ ├── market_hours.py # Market hours tools │ │ ├── market_performers.py # Market performers tools │ │ ├── quote.py # Stock quote tools │ │ ├── search.py # Search tools │ │ ├── statements.py # Financial statements tools │ │ └── technical_indicators.py # Technical analysis tools │ ├── resources/ # MCP resources implementation │ │ ├── company.py │ │ └── market.py │ ├── prompts/ # MCP prompts implementation │ │ └── templates.py │ └── agent_chat_client.py # OpenAI Agent-based chat client ├── scripts/ # Deployment and automation scripts │ └── mcp-aws-ecs-setup.sh # AWS ECS deployment script ├── tests/ # Test suite │ ├── conftest.py # Pytest fixtures │ ├── acceptance_tests.py # API integration tests │ ├── test_analyst.py # Tests for analyst tools │ ├── test_api_client.py # Tests for API functionality │ ├── test_calendar.py # Tests for calendar tools │ ├── test_charts.py # Tests for chart tools │ ├── test_commodities.py # Tests for commodities tools │ ├── test_company.py # Tests for company profile tools │ ├── test_crypto.py # Tests for cryptocurrency tools │ ├── test_etf.py # Tests for ETF tools │ ├── test_forex.py # Tests for forex tools │ ├── test_indices.py # Tests for indices tools │ ├── test_market.py # Tests for market tools │ ├── test_market_hours.py # Tests for market hours tools │ ├── test_market_performers.py # Tests for market performers tools │ ├── test_prompts.py # Tests for prompts │ ├── test_quotes.py # Tests for quote tools │ ├── test_resources.py # Tests for resources │ ├── test_search.py # Tests for search tools │ ├── test_server.py # Integration tests │ ├── test_statements.py # Tests for financial statements tools │ └── test_technical_indicators.py # Tests for technical indicators tools ├── Dockerfile # Docker configuration ├── docker-compose.yml # Docker Compose configuration └── server.py # Main server implementation ``` ## Usage ### Running the Server You can run the server in different ways: #### Local Development (stdio) ```bash # Run the server directly (stdio mode) python -m src.server # Or use the MCP CLI for development mcp dev src/server.py # Install in Claude Desktop mcp install src/server.py ``` #### SSE Server Mode ```bash # Run as an SSE server python -m src.server --sse --port 8000 ``` #### Streamable HTTP Server Mode > **Note**: Streamable HTTP transport is the recommended transport for production deployments, superseding SSE transport. The server supports Streamable HTTP transport with both stateful and stateless operation modes: ```bash # Stateful Streamable HTTP (maintains session state) python -m src.server --streamable-http --port 8000 # Stateless Streamable HTTP (no session persistence) python -m src.server --streamable-http --stateless --port 8000 # Stateless with JSON responses (instead of SSE streams) python -m src.server --streamable-http --stateless --json-response --port 8000 ``` **Transport Modes:** - **Stateful** (default): Maintains session state, supports event resumability, ideal for interactive clients - **Stateless**: No session persistence, suitable for multi-node deployments and load balancing - **JSON Response**: Returns JSON instead of SSE streams, useful for simpler HTTP clients **Endpoints:** - Streamable HTTP endpoint: `http://localhost:8000/mcp` - Health check endpoint: `http://localhost:8000/health` - All MCP operations (tools, resources, prompts) available via HTTP POST/GET **Docker Support:** ```bash # Default SSE mode docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest # Streamable HTTP stateful mode docker run -p 8000:8000 -e TRANSPORT=streamable-http -v $(pwd)/.env:/app/.env ghcr.i … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [cdtait](https://github.com/cdtait) - **Source:** [cdtait/fmp-mcp-server](https://github.com/cdtait/fmp-mcp-server) - **License:** MIT - **Homepage:** https://github.com/cdtait/fmp-mcp-server Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-cdtait-fmp-mcp-server - Seller: https://agentstack.voostack.com/s/cdtait - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.