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. 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:

   git clone https://github.com/cdtait/fmp-mcp-server.git

   cd fmp-mcp-server

   

2. Set up the environment using either pip or uv:

### Option 1: Using pip (Standard)

   # 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)

   # 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:

   # 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.

4. Set up your OpenAI API key (if using the chat agent):

   # Add your OpenAI API key to the .env file

   echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env

   

5. Verify installation with tests:

   # 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