Financial Modeling Prep MCP (Model Context Protocol) Server

A Model Context Protocol (MCP) implementation for Financial Modeling Prep, enabling AI assistants to access and analyze financial data, stock information, company fundamentals, and market insights.

Server Architecture
Configuration & Mode Enforcement
- Server Modes
- Configuration Precedence
Usage
Making HTTP Requests
- Session Configuration
- Request Examples
Selective Tool Loading
Dynamic Toolset Management (BETA)
Available Tools
Obtaining a Financial Modeling Prep Access Token
Contributing
- Development Setup
- Running Tests
Issues and Bug Reports
License

Features

Comprehensive Coverage: Access to 253+ financial tools across 24 categories
Tool Set Filtering: Load only the tools you need to reduce complexity and improve performance
Real-time Data: Live stock quotes, market data, and financial information
Financial Statements: Income statements, balance sheets, cash flow statements, and financial ratios
Market Analysis: Technical indicators, analyst estimates, and market performance metrics
Economic Data: Treasury rates, economic indicators, and macroeconomic information
Alternative Data: ESG scores, insider trading, congressional trading, and social sentiment

Server Architecture

This MCP server uses a stateful session-based architecture powered by the Smithery SDK for request/session lifecycle. Resource reuse is handled via a client-level cache keyed by clientId (derived from the access token).

Key Features:

Client-level Caching: Exactly one McpServer/DynamicToolsetManager is maintained per clientId. Tokenless requests use a per-request anonymous id (no reuse).
Session Isolation: Sessions are managed by the SDK, but caching does not use sessionId.
Stateful Management: Sessions maintain their state across multiple requests
Mode Enforcement: Server-level configurations can override session-level settings
HTTP-based Protocol: Communicates via HTTP with JSON-RPC formatted messages
Dynamic Tool Management: Tools can be loaded/unloaded at runtime per session

Request Flow:

Client Request → HTTP POST to /mcp endpoint
Session Management → Server creates or retrieves session based on config (caching and reuse are keyed by clientId)
Mode Resolution → Server determines operational mode (Dynamic/Static/Legacy)
Tool Registration → Session-specific tools are loaded based on resolved mode
Request Processing → MCP request is processed with available tools
Response → JSON-RPC response sent back to client

Configuration & Mode Enforcement

The server supports multiple configuration methods with a clear precedence hierarchy to ensure predictable behavior.

Server Modes

The server operates in one of three modes:

🔀 Dynamic Mode (DYNAMIC_TOOL_DISCOVERY=true)
- Starts with only 3 meta-tools: enable_toolset, disable_toolset, get_toolset_status
- Tools loaded on-demand via meta-tool calls
- Best for: Flexible, task-specific workflows where tool requirements change
🔧 Static Mode (FMP_TOOL_SETS=search,company,quotes)
- Pre-loads specific toolsets at session creation
- All specified tools available immediately
- Best for: Known, consistent tool requirements with predictable usage patterns
📚 Legacy Mode (default, no specific configuration)
- Loads all 253+ tools at session creation
- Maximum compatibility with all features available
- Best for: Full feature access without configuration complexity

Configuration Precedence

The server follows a strict precedence hierarchy when determining the operational mode:

🥇 CLI Arguments (highest priority)
   ↓
🥈 Environment Variables
   ↓
🥉 Session Configuration (lowest priority)

⚠️ Important Mode Enforcement Behavior

When server-level configurations are set (CLI arguments or environment variables), they override all session-level configurations for ALL sessions. This ensures consistent behavior across the entire server instance.

Example Override Scenario:

# Server started with CLI argument
npm run dev -- --dynamic-tool-discovery

# ALL session requests will use Dynamic Mode, regardless of session config
# Session config like {"FMP_TOOL_SETS": "search,company"} will be IGNORED

Configuration Methods:

CLI Arguments (Server-level - overrides everything)

npm run dev -- --fmp-token=TOKEN --dynamic-tool-discovery
npm run dev -- --fmp-token=TOKEN --fmp-tool-sets=search,company,quotes
npm run dev -- --port=4000 --fmp-token=TOKEN

Environment Variables (Server-level - overrides session configs)

DYNAMIC_TOOL_DISCOVERY=true npm run dev
FMP_TOOL_SETS=search,company,quotes npm run dev

Session Configuration (Session-level - via HTTP query parameter)

# Base64 encoded JSON config in query parameter
curl -X POST "http://localhost:8080/mcp?config=eyJEWU5BTUlDX1RPT0xfRElTQ09WRVJZIjoidHJ1ZSJ9"

⚠️ Configuration Warnings

Server-level modes are GLOBAL: They affect all sessions on the server instance
Session configs are IGNORED when server-level modes are active
No mixing: You cannot have different modes for different sessions when server-level enforcement is active
Restart required: Changing server-level configurations requires server restart

Selective Tool Loading

While MCP clients can filter tools automatically, large tool sets may impact performance. To optimize your experience, you can specify which tool categories to load instead of loading all 253 tools at once:

Available Tool Sets

Tool Set	Description	Example Tools
`search`	Search & Directory	Search stocks, company lookup, symbol directories
`company`	Company Profile & Info	Company profiles, executives, employee count
`quotes`	Real-time Quotes	Live stock prices, market data, price changes
`statements`	Financial Statements	Income statements, balance sheets, cash flow, ratios
`calendar`	Financial Calendar	Earnings calendar, dividends, IPOs, stock splits
`charts`	Price Charts & History	Historical prices, technical charts, market movements
`news`	Financial News	Market news, press releases, financial articles
`analyst`	Analyst Coverage	Price targets, ratings, analyst estimates
`market-performance`	Market Performance	Sector performance, gainers, losers, most active
`insider-trades`	Insider Trading	Corporate insider activity, ownership changes
`institutional`	Institutional Holdings	13F filings, fund holdings, institutional ownership
`indexes`	Market Indexes	S&P 500, NASDAQ, Dow Jones, index constituents
`economics`	Economic Data	Treasury rates, GDP, inflation, economic indicators
`crypto`	Cryptocurrency	Crypto prices, market data, digital assets
`forex`	Foreign Exchange	Currency pairs, exchange rates, forex data
`commodities`	Commodities	Gold, oil, agricultural products, futures
`etf-funds`	ETFs & Mutual Funds	Fund holdings, performance, fund information
`esg`	ESG & Sustainability	Environmental, social, governance ratings
`technical-indicators`	Technical Indicators	RSI, SMA, EMA, MACD, Bollinger Bands
`senate`	Government Trading	Congressional and Senate trading disclosures
`sec-filings`	SEC Filings	10-K, 10-Q, 8-K filings, regulatory documents
`earnings`	Earnings & Transcripts	Earnings reports, call transcripts
`dcf`	DCF Valuation	Discounted cash flow models, valuations
`bulk`	Bulk Data	Large-scale data downloads for analysis

Dynamic Toolset Management (BETA)

🚧 This feature is currently in BETA. API and behavior may change in future versions.

The Dynamic Toolset Management feature allows you to enable and disable tool categories at runtime instead of pre-configuring them at startup. This provides more flexibility and can help optimize performance by loading only the tools you need when you need them.

How It Works

When dynamic toolset management is enabled, each session starts with only 3 meta-tools:

enable_toolset - Enable a specific toolset during runtime
disable_toolset - Disable a previously enabled toolset
get_toolset_status - Check which toolsets are currently active

AI assistants can then use these meta-tools to dynamically load and unload specific tool categories as needed for different tasks within their session.

Configuration Options

Server-Level Configuration (Affects All Sessions)

Command Line Arguments:

# Enable dynamic toolset management for all sessions
npm run dev -- --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

# Production deployment
node dist/index.js --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

Environment Variables:

# Set environment variable
export DYNAMIC_TOOL_DISCOVERY=true
export FMP_ACCESS_TOKEN=YOUR_TOKEN
npm run dev

# Or inline
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=YOUR_TOKEN npm start

Docker:

# docker-compose.yml
version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    environment:
      - FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
      - DYNAMIC_TOOL_DISCOVERY=true # Enable for all sessions

Session-Level Configuration (When No Server Override)

When no server-level dynamic mode is set, individual sessions can request dynamic mode:

# Base64 encode: {"DYNAMIC_TOOL_DISCOVERY":"true"}
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

Example Workflow

Start server with dynamic mode:
```
DYNAMIC_TOOL_DISCOVERY=true npm start
```

AI assistant initializes session and gets meta-tools:

// Response includes only 3 meta-tools:
{
  "tools": [
    { "name": "enable_toolset", "description": "Enable a specific toolset" },
    { "name": "disable_toolset", "description": "Disable a toolset" },
    { "name": "get_toolset_status", "description": "Check active toolsets" }
  ]
}

AI assistant enables needed toolsets:

// Enable search toolset
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"enable_toolset","arguments":{"toolset":"search"}}}

// Enable quotes toolset
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"enable_toolset","arguments":{"toolset":"quotes"}}}

AI assistant uses the enabled tools:

// Now can use search and quotes tools
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"searchSymbol","arguments":{"query":"AAPL"}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"getQuote","arguments":{"symbol":"AAPL"}}}

AI assistant can disable unused toolsets:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "disable_toolset",
    "arguments": { "toolset": "search" }
  }
}

Benefits

Performance: Start faster with fewer tools loaded initially per session
Flexibility: Load only the tools needed for current tasks
Resource Efficiency: Reduce memory usage by disabling unused toolsets per session
Task-Oriented: Perfect for AI assistants that work on specific financial analysis tasks
Session Isolation: Each session can have different active toolsets

Usage

Registries

For production environments, you can use this MCP server through various registries that provide hosted and managed MCP servers:

Smithery.ai

🚀 View on Smithery.ai

Smithery is a platform that helps developers find and ship AI-native services designed to communicate with AI agents. All services follow the Model Context Protocol (MCP) specification and provide:

Centralized discovery of MCP servers
Hosting and distribution for MCP servers
Standardized interfaces for tool integration

Session Configuration with Smithery

When using Smithery, you can configure individual sessions by passing configuration in your MCP client. The Smithery platform handles the HTTP request formatting and session management.

Example configurations for Smithery:

// Dynamic mode session
{
  "DYNAMIC_TOOL_DISCOVERY": "true"
}

// Static mode session
{
  "FMP_TOOL_SETS": "search,company,quotes"
}

// Legacy mode (all tools)
{}

For detailed integration instructions, follow the Smithery documentation for connecting MCP clients to hosted servers.

Glama.ai

Use on Glama.ai

Contexaai.com

Use on Contexaai.com

HTTP Server & Local Development

The server runs as an HTTP server that exposes a Model Context Protocol endpoint. Each request can include session-specific configuration via query parameters.

Basic Server Setup

Local Development:

# Clone and setup
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server
npm install
npm run build

# Run in development
FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

# Or with CLI arguments
npm run dev -- --fmp-token=YOUR_TOKEN
npm run dev -- --port=4000 --fmp-token=YOUR_TOKEN

Server-Level Mode Configuration

🔐 Server-Level Dynamic Mode (All Sessions Use Dynamic Mode):

# CLI argument (highest priority)
npm run dev -- --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

# Environment variable
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

🔧 Server-Level Static Mode (All Sessions Use Specified Toolsets):

# CLI argument (highest priority)
npm run dev -- --fmp-token=YOUR_TOKEN --fmp-tool-sets=search,company,quotes

# Environment variable
FMP_TOOL_SETS=search,company,quotes FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

📚 Server-Level Legacy Mode (All Sessions Get All Tools):

# Default behavior - no specific configuration
npm run dev -- --fmp-token=YOUR_TOKEN
FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

Custom Port Configuration

# Change server port via environment variable
PORT=4000 npm run dev -- --fmp-token=YOUR_TOKEN

# Change server port via CLI argument
npm run dev -- --port=4000 --fmp-token=YOUR_TOKEN

Docker Usage

Docker deployment supports all configuration methods with proper environment variable handling.

Using Docker with Environment Variables

# Basic deployment
docker run -p 8080:8080 -e FMP_ACCESS_TOKEN=YOUR_TOKEN your-image-name

# With server-level dynamic mode
docker run -p 8080:8080 \
  -e FMP_ACCESS_TOKEN=YOUR_TOKEN \
  -e DYNAMIC_TOOL_DISCOVERY=true \
  your-image-name

# With server-level static mode
docker run -p 8080:8080 \
  -e FMP_ACCESS_TOKEN=YOUR_TOKEN \
  -e FMP_TOOL_SETS=search,company,quotes \
  your-image-name

Using Docker Compose

Create a docker-compose.yml file:

version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    environment:
      - FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
      - PORT=8080
      # Optional: Server-level mode enforcement
      - DYNAMIC_TOOL_DISCOVERY=true # All sessions use dynamic mode
      # OR
      - FMP_TOOL_SETS=search,company,quotes # All sessions use these toolsets
      # OR leave both unset for legacy mode (all tools)

Then run:

docker-compose up

Using .env File with Docker Compose

Create a .env file:

FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
PORT=8080

# Optional: Choose ONE server-level mode
DYNAMIC_TOOL_DISCOVERY=true
# OR
# FMP_TOOL_SETS=search,company,quotes
# OR leave both commented for legacy mode

And reference it in your docker-compose.yml:

version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    env_file:
      - .env

Example System Prompts

The following system prompts are designed to help AI assistants effectively use this MCP server for financial analysis tasks. Choose the appropriate prompt based on your server configuration mode.

For Dynamic Toolset Mode

You are an expert financial analyst AI with access to comprehensive market data tools.

CORE RULES:
- Always use tools for current market data; never rely on outdated information or estimates
- Check conversation history to avoid redundant tool calls
- Provide concise, data-driven responses
- Always include: "This is not financial advice"

DYNAMIC TOOLSET MANAGEMENT:
Your tools are organized into categories ("toolsets") that must be enabled before use. You have a 4-toolset maximum at any time.

Available toolsets: search, company, quotes, statements, calendar, charts, news, analyst, market-performance, insider-trades, institutional, indexes, economics, crypto, forex, commodities, etf-funds, esg, technical-indicators, senate, sec-filings, earnings, dcf, bulk

EXECUTION WORKFLOW:
1. ENABLE: Use enable_toolset for required categories based on the user's query
2. VERIFY: Call get_toolset_status to confirm active toolsets. If >4 active, use disable_toolset to remove the least relevant
3. EXECUTE: Call specific tools from enabled toolsets
4. CLEAN UP: Consider disabling unused toolsets when switching to different analysis types

FAILURE PROTOCOL:
If tools fail repeatedly or data is unavailable, state: "I cannot find the requested information with the available tools" and stop attempting.

Begin each analysis by enabling the appropriate toolsets for the user's request.

For Static Toolset Mode

You are an expert financial analyst AI with access to comprehensive market data tools.

CORE RULES:
- Always use tools for current market data; never rely on outdated information or estimates
- Check conversation history to avoid redundant tool calls
- Provide concise, data-driven responses
- Always include: "This is not financial advice"

STATIC TOOLSET CONFIGURATION:
Your tools are pre-loaded and immediately available. All configured toolsets remain active throughout the session.

EXECUTION WORKFLOW:
1. IDENTIFY: Determine which tools from your available toolsets best address the user's query
2. EXECUTE: Call the appropriate tools directly - no toolset management needed
3. ANALYZE: Process the data and provide insights based on the results

TOOL CATEGORIES:
Your available tools span multiple categories including company profiles, financial statements, market quotes, technical analysis, news sentiment, and economic indicators. Use the most relevant tools for each analysis.

FAILURE PROTOCOL:
If tools fail repeatedly or data is unavailable, state: "I cannot find the requested information with the available tools" and stop attempting.

Proceed directly to analysis using your available tools based on the user's request.

Usage Tips

Dynamic Mode: Best for exploratory analysis where tool requirements change frequently. The AI assistant will manage toolsets based on the current task.
Static Mode: Best for consistent, predictable workflows where the same types of analysis are performed repeatedly.
Legacy Mode: Use the Static Mode prompt when all tools are pre-loaded (default configuration).

Human-Friendly Capabilities Prompt

This server provides a human-friendly prompt to list capabilities in one shot.

Name: list_mcp_assets
Output sections: Server Capabilities, Prompts, Tools (mode-aware), Resources (health snapshot), Quick Start
Exposed only as an MCP prompt (no tool alias)

List assets via prompts

# 1) Initialize (example: dynamic mode session)
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": { "protocolVersion": "2024-11-05", "clientInfo": {"name": "client", "version": "1.0.0"}, "capabilities": {} }
  }'

# 2) List prompts
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"prompts/list","params":{}}'

# 3) Get the capabilities prompt
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"list_mcp_assets","arguments":{}}}'

Notes:

The Tools section adapts to the effective mode (Dynamic/Static/Legacy). In legacy mode, it summarizes categories instead of listing all 250+ tools.
In Static mode, toolsets shown are the authoritative list from the server’s mode enforcer (single source of truth). Session FMP_TOOL_SETS may request Static mode, but server-level configuration controls the final toolsets.
The Resources section includes a lightweight health snapshot (uptime, memory summary, version, mode).

Making HTTP Requests

The server exposes a Model Context Protocol endpoint at /mcp that accepts JSON-RPC formatted requests. Each request can include optional session configuration via query parameters.

Endpoint Format

POST http://localhost:8080/mcp[?config=BASE64_ENCODED_CONFIG]

Required Headers

Content-Type: application/json
Accept: application/json, text/event-stream

Session Configuration

Session configurations are passed as Base64-encoded JSON in the config query parameter. This allows each session to have different tool configurations when no server-level mode enforcement is active.

Configuration Examples:

Dynamic Mode Session:

# Configuration: {"DYNAMIC_TOOL_DISCOVERY":"true"}
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
# Result: eyJEWU5BTUlDX1RPT0xfRElTQ09WRVJZIjoidHJ1ZSJ9

Static Mode Session:

# Configuration: {"FMP_TOOL_SETS":"search,company,quotes"}
CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,company,quotes"}' | base64)
# Result: eyJGTVBfVE9PTF9TRVRTIjoic2VhcmNoLGNvbXBhbnkscXVvdGVzIn0=

Legacy Mode Session:

# Configuration: {} (empty object)
CONFIG_BASE64=$(echo -n '{}' | base64)
# Result: e30=

Request Examples

1. Initialize a Dynamic Mode Session

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "fmp-mcp-server",
      "version": "1.0.0"
    }
  }
}

2. List Available Tools

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Expected Response (Dynamic Mode):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "enable_toolset",
        "description": "Enable a specific toolset during runtime",
        "inputSchema": {
          "type": "object",
          "properties": {
            "toolset": {
              "type": "string",
              "description": "Name of the toolset to enable"
            }
          },
          "required": ["toolset"]
        }
      },
      {
        "name": "disable_toolset",
        "description": "Disable a previously enabled toolset"
      },
      {
        "name": "get_toolset_status",
        "description": "Check which toolsets are currently active"
      }
    ]
  }
}

3. Enable a Toolset (Dynamic Mode)

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "enable_toolset",
      "arguments": {
        "toolset": "search"
      }
    }
  }'

4. Call a Financial Tool

CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "searchSymbol",
      "arguments": {
        "query": "Apple"
      }
    }
  }'

5. Get Stock Quote

CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "getQuote",
      "arguments": {
        "symbol": "AAPL"
      }
    }
  }'

Session and Client Behavior

Session Persistence: Each unique config parameter creates a separate session (SDK-managed)
Tool State: In dynamic mode, enabled/disabled toolsets may be reused for the same clientId across requests
Isolation: Sessions don't interfere with each other's tool configurations; caching is keyed by clientId
Caching: Client storage (LRU + TTL) maintains one McpServer/DynamicToolsetManager per clientId

Cache Reuse Policy (Session-Config Aware)

For the same clientId (derived from token), the server compares each request’s desired mode and static tool sets against the cached instance.
If there is a difference and there is NO server-level mode enforcement, a new McpServer instance is created and the cache entry is replaced.
If a server-level mode is enforced (via CLI/env), session-level changes are ignored and the cached instance is reused.
Static tool set comparison is order-insensitive (e.g., search,company equals company,search).

Error Handling

Common error responses:

// Invalid configuration
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Bad Request: Invalid configuration"
  },
  "id": null
}

// Tool not available
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Tool not found: toolName"
  },
  "id": 1
}

// Missing required parameters
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Missing required parameter: symbol"
  },
  "id": 2
}

Available Tools

⚠️ Important: Mode Enforcement Behavior

Server-Level Configurations Override Session Configurations:

When CLI arguments (--dynamic-tool-discovery, --fmp-tool-sets) are used, they apply to ALL sessions

When environment variables (DYNAMIC_TOOL_DISCOVERY, FMP_TOOL_SETS) are set, they apply to ALL sessions

Session-level configurations via query parameters are IGNORED when server-level modes are active

This ensures consistent behavior across all sessions on a server instance

Configuration Precedence: CLI Arguments > Environment Variables > Session Configuration

Example: If server started with --dynamic-tool-discovery, ALL sessions will use dynamic mode even if they request {"FMP_TOOL_SETS":"search,company"} in their session config.

This MCP provides the following tools for AI assistants to access financial data:

Search Tools

searchSymbol: Search for stock symbols by name or ticker
searchName: Search for companies by name
searchCIK: Search for companies by CIK number
searchCUSIP: Search for securities by CUSIP number
searchISIN: Search for securities by ISIN number
stockScreener: Screen stocks based on various criteria
searchExchangeVariants: Search for symbol variants across different exchanges
searchCompaniesByName: Search for companies by name
searchCompaniesBySymbol: Search for companies by symbol
searchCompaniesByCIK: Search for companies by CIK number

Directory and Symbol Lists

getCompanySymbols: Get a list of all company symbols
getFinancialStatementSymbols: Get a list of companies with available financial statements
getCIKList: Get a list of CIK numbers for SEC-registered entities
getSymbolChanges: Get a list of stock symbol changes
getETFList: Get a list of ETFs
getActivelyTradingList: Get a list of actively trading companies
getEarningsTranscriptList: Get a list of companies with earnings transcripts
getAvailableExchanges: Get a list of available exchanges
getAvailableSectors: Get a list of available sectors
getAvailableIndustries: Get a list of available industries
getAvailableCountries: Get a list of available countries
getAvailableTranscriptSymbols: Get a list of symbols with available transcripts
getAllIndustryClassification: Get all industry classifications
getIndustryClassificationList: Get a list of industry classifications

Financial Statements

getIncomeStatement: Get company income statements
getBalanceSheet: Get company balance sheet statements
getBalanceSheetStatement: Get company balance sheet statements
getCashFlowStatement: Get company cash flow statements
getIncomeStatementAsReported: Get income statements as reported
getBalanceSheetAsReported: Get balance sheet statements as reported
getBalanceSheetStatementAsReported: Get balance sheet statements as reported
getCashFlowStatementAsReported: Get cash flow statements as reported
getFullFinancialStatementAsReported: Get full financial statements as reported
getFinancialStatementFullAsReported: Get full financial statements as reported
getFinancialReportDates: Get dates of available financial reports
getFinancialReportsDates: Get dates of available financial reports
getLatestFinancialStatements: Get latest financial statements
getIncomeStatementTTM: Get trailing twelve months income statements
getBalanceSheetStatementTTM: Get trailing twelve months balance sheet statements
getCashFlowStatementTTM: Get trailing twelve months cash flow statements
getIncomeStatementGrowth: Get income statement growth
getBalanceSheetStatementGrowth: Get balance sheet statement growth
getCashFlowStatementGrowth: Get cash flow statement growth
getFinancialStatementGrowth: Get financial statement growth
getFinancialReportJSON: Get financial report in JSON format
getFinancialReportXLSX: Get financial report in XLSX format
getRevenueProductSegmentation: Get revenue product segmentation
getRevenueGeographicSegmentation: Get revenue geographic segmentation

Financial Metrics and Analysis

getKeyMetrics: Get key financial metrics for a company
getKeyMetricsTTM: Get key metrics for trailing twelve months
getRatios: Get financial ratios for a company
getFinancialRatios: Get financial ratios for a company
getFinancialRatiosTTM: Get financial ratios for trailing twelve months
getFinancialGrowth: Get financial growth metrics
getIncomeStatementGrowth: Get income statement growth metrics
getBalanceSheetGrowth: Get balance sheet growth metrics
getCashFlowStatementGrowth: Get cash flow statement growth metrics
getDCFValuation: Get DCF (Discounted Cash Flow) valuation for a stock
getLeveredDCFValuation: Get levered DCF valuation for a stock
calculateCustomDCF: Calculate custom DCF valuation with user-defined parameters
calculateCustomLeveredDCF: Calculate custom levered DCF valuation with user-defined parameters
getEnterpriseValue: Get enterprise value for a company
getFinancialScore: Get financial score for a company
getFinancialScores: Get financial scores for a company
getOwnerEarnings: Get owner earnings for a company

Technical Indicators

getSMA: Get Simple Moving Average (SMA) indicator
getEMA: Get Exponential Moving Average (EMA) indicator
getWMA: Get Weighted Moving Average (WMA) indicator
getDEMA: Get Double Exponential Moving Average (DEMA) indicator
getTEMA: Get Triple Exponential Moving Average (TEMA) indicator
getWilliams: Get Williams %R indicator
getADX: Get Average Directional Index (ADX) indicator
getStandardDeviation: Get Standard Deviation indicator
getRSI: Get Relative Strength Index (RSI) indicator

Quotes and Price Data

getQuote: Get current stock quote information
getBatchQuotes: Get quotes for multiple symbols
getQuoteShort: Get abbreviated stock quote information
getBatchQuotesShort: Get abbreviated quotes for multiple symbols
getHistoricalPrice: Get historical price data
getHistoricalPriceChart: Get historical price chart data
getHistoricalDailyPrice: Get historical daily price data
getHistoricalStockSplits: Get historical stock splits
getHistoricalDividends: Get historical dividends
getTechnicalIndicator: Get technical indicators for a stock
getLightChart: Get light version of price chart
getFullChart: Get full version of price chart
getUnadjustedChart: Get unadjusted price chart
getDividendAdjustedChart: Get dividend-adjusted price chart
getIntradayChart: Get intraday price chart
getAftermarketQuote: Get aftermarket quote
getAftermarketTrade: Get aftermarket trade data
getBatchAftermarketQuote: Get batch aftermarket quotes
getBatchAftermarketTrade: Get batch aftermarket trade data
getStockPriceChange: Get stock price change information

Market Indexes and Performance

getIndexList: Get a list of all market indexes
getIndexQuotes: Get quotes for market indexes
getIndexQuote: Get quote for a specific index
getIndexShortQuote: Get abbreviated quote for an index
getAllIndexQuotes: Get quotes for all market indexes
getSP500Constituents: Get S&P 500 constituent companies
getHistoricalSP500Changes: Get historical S&P 500 changes
getNasdaqConstituents: Get NASDAQ constituent companies
getDowJonesConstituents: Get Dow Jones constituent companies
getHistoricalNasdaqChanges: Get historical NASDAQ changes
getHistoricalDowJonesChanges: Get historical Dow Jones changes
getSectorPerformance: Get sector performance data
getHistoricalSectorPerformance: Get historical sector performance
getBiggestGainers: Get biggest gaining stocks
getBiggestLosers: Get biggest losing stocks
getMostActiveStocks: Get most active stocks
getHistoricalIndexFullChart: Get historical index full chart
getHistoricalIndexLightChart: Get historical index light chart
getIndex1MinuteData: Get 1-minute index data
getIndex5MinuteData: Get 5-minute index data
getIndex1HourData: Get 1-hour index data
getSectorPerformanceSnapshot: Get sector performance snapshot
getSectorPESnapshot: Get sector PE ratio snapshot
getIndustryPerformanceSnapshot: Get industry performance snapshot
getIndustryPerformanceSummary: Get industry performance summary
getIndustryPESnapshot: Get industry PE ratio snapshot
getHistoricalIndustryPerformance: Get historical industry performance
getHistoricalIndustryPE: Get historical industry PE ratios
getHistoricalSectorPE: Get historical sector PE ratios

Market Data

getMarketHours: Get market hours for a specific exchange
getExchangeMarketHours: Get market hours for a specific exchange
getHolidaysByExchange: Get holidays for a specific exchange with optional date range filtering
getAllExchangeMarketHours: Get market hours for all exchanges
getEarningsCalendar: Get earnings announcement calendar
getIPOCalendar: Get initial public offering calendar
getStockSplitCalendar: Get stock split calendar
getDividendCalendar: Get dividend calendar
getEconomicCalendar: Get economic events calendar
getIPODisclosures: Get IPO disclosures
getIPOProspectuses: Get IPO prospectuses

News and Press Releases

getFMPArticles: Get financial news articles from FMP
getGeneralNews: Get general financial news
getStockNews: Get news for specific stocks
getStockNewsSentiment: Get news with sentiment analysis
getPressReleases: Get company press releases
searchStockNews: Search stock news
searchPressReleases: Search press releases
getCryptoNews: Get cryptocurrency news
searchCryptoNews: Search cryptocurrency news
getForexNews: Get forex news
searchForexNews: Search forex news

SEC Filings

getLatestFinancialFilings: Get latest financial filings
getFilingsBySymbol: Get filings by symbol
getFilingsByCIK: Get filings by CIK
getFilingsByFormType: Get filings by form type
getLatest8KFilings: Get latest 8-K filings
getSecFilingExtract: Get SEC filing extract
getFilingExtractAnalyticsByHolder: Get filing extract analytics by holder

Insider and Institutional Trading

getInsiderTrading: Get insider trading data
getInsiderRoster: Get insider roster for a company
getInsiderRosterStatistics: Get statistics on insider roster
getInsiderTransactionTypes: Get types of insider transactions
getInsiderOwnership: Get insider ownership information
getInstitutionalOwnership: Get institutional ownership data
getInstitutionalHolders: Get institutional holders for a company
getInstitutionalHoldersList: Get list of institutional holders
getInstitutionalHolderPortfolioDates: Get portfolio dates for institutional holders
get13FFilings: Get 13F filings
get13FDates: Get dates of 13F filings
getForm13FFilingDates: Get 13F filing dates
getLatestInsiderTrading: Get latest insider trading data
searchInsiderTrades: Search insider trades
searchInsiderTradesByReportingName: Search insider trades by reporting name
getInsiderTradeStatistics: Get insider trade statistics
getLatestInstitutionalFilings: Get latest institutional filings
getHolderPerformanceSummary: Get holder performance summary
getHolderIndustryBreakdown: Get holder industry breakdown
getPositionsSummary: Get positions summary

ETFs and Funds

getETFHolder: Get ETF holder information
getETFSectorWeighting: Get ETF sector weightings
getETFCountryWeighting: Get ETF country weightings
getETFExposure: Get ETF exposure to stocks
getFundInfo: Get fund information
getFundHolder: Get fund holder information
getFundSectorWeighting: Get fund sector weightings
getFundHoldings: Get fund holdings
getFundCountryAllocation: Get fund country allocation
getFundAssetExposure: Get fund asset exposure
getDisclosure: Get latest fund disclosure holders information
getFundDisclosure: Get comprehensive fund disclosure data by year/quarter
searchFundDisclosures: Search fund disclosures by holder name
getFundDisclosureDates: Get fund disclosure dates (with optional CIK)
getETFHoldersBulk: Get ETF holders in bulk
getETFQuotes: Get ETF quotes
getMutualFundQuotes: Get mutual fund quotes

Government Trading

getGovernmentTradingList: Get government trading list
getSenateTrading: Get senate trading data
getHouseTrading: Get house trading data
getSenateTrades: Get senate trades
getSenateTradesByName: Get senate trades by name
getHouseTrades: Get house trades
getHouseTradesByName: Get house trades by name
getLatestSenateDisclosures: Get latest senate disclosures
getLatestHouseDisclosures: Get latest house disclosures

Cryptocurrency and Forex

getCryptocurrencyList: Get a list of cryptocurrencies
getCryptocurrencyQuote: Get cryptocurrency quote
getCryptocurrencyShortQuote: Get abbreviated cryptocurrency quote
getCryptocurrencyBatchQuotes: Get quotes for multiple cryptocurrencies
getCryptocurrencyHistoricalLightChart: Get light historical cryptocurrency chart
getCryptocurrencyHistoricalFullChart: Get full historical cryptocurrency chart
getCryptocurrency1MinuteData: Get 1-minute cryptocurrency data
getCryptocurrency5MinuteData: Get 5-minute cryptocurrency data
getCryptocurrency1HourData: Get 1-hour cryptocurrency data
getForexList: Get a list of forex pairs
getForexQuote: Get forex pair quote
getForexShortQuote: Get abbreviated forex quote
getForexBatchQuotes: Get quotes for multiple forex pairs with optional short format
getForexHistoricalLightChart: Get light historical forex chart with optional date range
getForexHistoricalFullChart: Get full historical forex chart with optional date range
getForex1MinuteData: Get 1-minute forex data with optional date range
getForex5MinuteData: Get 5-minute forex data with optional date range
getForex1HourData: Get 1-hour forex data with optional date range

Earnings

getEarningsReports: Get earnings reports
getEarningsTranscript: Get earnings transcript
getEarningsTranscriptDates: Get earnings transcript dates
getLatestEarningsTranscripts: Get latest earnings transcripts
getEarningsSurprisesBulk: Get bulk earnings surprises

Special Data Sets

getCOTList: Get Commitment of Traders (COT) list
getCOTReports: Get COT reports for a specific symbol with optional date range filtering
getCOTAnalysis: Get COT analysis for a specific symbol with optional date range filtering
getGovernmentTradingList: Get government trading list
getSenateTrading: Get senate trading data
getHouseTrading: Get house trading data
getESGDisclosures: Get ESG disclosures for a specific symbol
getESGRatings: Get ESG ratings for a specific symbol
getESGBenchmarks: Get ESG benchmark data with optional year filtering

Commodities

listCommodities: Get a list of all available commodities with their symbols, names, exchanges, trade months, and currencies

Economics

getTreasuryRates: Get treasury rates with optional date range filtering
getEconomicIndicators: Get economic indicators by name with optional date range filtering
getEconomicCalendar: Get economic events calendar with optional date range filtering
getMarketRiskPremium: Get market risk premium data

Fundraisers

getLatestCrowdfundingCampaigns: Get latest crowdfunding campaigns
searchCrowdfundingCampaigns: Search crowdfunding campaigns
getCrowdfundingCampaignsByCIK: Get crowdfunding campaigns by CIK
getLatestEquityOfferings: Get latest equity offerings
searchEquityOfferings: Search equity offerings
getEquityOfferingsByCIK: Get equity offerings by CIK

Bulk Data Tools

Important Note: All bulk endpoints return data in CSV format as raw strings rather than parsed JSON objects. This endpoint returns the response as a CSV file. The provided sample response represents an individual record. This design preserves the original FMP API format and provides better performance for large datasets.

getCompanyProfilesBulk: Get bulk company profiles (CSV format)
getStockRatingsBulk: Get bulk stock ratings (CSV format)
getDCFValuationsBulk: Get bulk DCF valuations (CSV format)
getFinancialScoresBulk: Get bulk financial scores (CSV format)
getPriceTargetSummariesBulk: Get bulk price target summaries (CSV format)
getUpgradesDowngradesConsensusBulk: Get bulk upgrades/downgrades consensus (CSV format)
getKeyMetricsTTMBulk: Get bulk key metrics TTM (CSV format)
getRatiosTTMBulk: Get bulk ratios TTM (CSV format)
getStockPeersBulk: Get bulk stock peers (CSV format)
getEODDataBulk: Get bulk end-of-day price data (CSV format)
getIncomeStatementsBulk: Get bulk income statements (CSV format)
getIncomeStatementGrowthBulk: Get bulk income statement growth data (CSV format)
getBalanceSheetStatementsBulk: Get bulk balance sheet statements (CSV format)
getBalanceSheetGrowthBulk: Get bulk balance sheet growth data (CSV format)
getCashFlowStatementsBulk: Get bulk cash flow statements (CSV format)
getCashFlowGrowthBulk: Get bulk cash flow growth data (CSV format)
getFinancialRatiosBulk: Get bulk financial ratios (CSV format)
getKeyMetricsBulk: Get bulk key metrics (CSV format)
getFinancialGrowthBulk: Get bulk financial growth data (CSV format)

Obtaining a Financial Modeling Prep Access Token

To get a Financial Modeling Prep access token:

Visit the Financial Modeling Prep website
Click on "Sign Up" to create an account
Verify your email address
After signing in, navigate to your Dashboard to find your API key
For more data access, consider upgrading to a paid plan (Starter, Premium, Ultimate, or Enterprise)

Financial Modeling Prep offers different pricing tiers with varying levels of data access and API call limits. For more information, visit the FMP Pricing page.

Contributing

Contributions are welcome! Here's how you can contribute:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Every pull request triggers a GitHub Actions workflow that verifies the build process.

Development Setup

# Clone the repository
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with your API key
FMP_ACCESS_TOKEN=your_api_key npm run dev

# Or specify the API key directly via CLI argument
npm run dev -- --fmp-token=your_api_key

The development server will start on port 8080 by default. You can configure the port using the PORT environment variable:

PORT=4000 FMP_ACCESS_TOKEN=your_api_key npm run dev

Development with Server-Level Mode Enforcement

Server-Level Static Mode (All Sessions Use Specific Toolsets):

# Environment variable approach
FMP_TOOL_SETS=search,company,quotes FMP_ACCESS_TOKEN=your_api_key npm run dev

# CLI argument approach (higher precedence)
npm run dev -- --fmp-token=your_api_key --fmp-tool-sets=search,company,quotes

Server-Level Dynamic Mode (All Sessions Start with Meta-Tools):

# Environment variable approach
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=your_api_key npm run dev

# CLI argument approach (higher precedence)
npm run dev -- --fmp-token=your_api_key --dynamic-tool-discovery

Session-Level Configuration (Default - No Server Enforcement):

# Start server without mode enforcement
npm run dev -- --fmp-token=your_api_key

# Individual sessions can then specify their own configurations via HTTP requests

Testing Different Configurations

When developing, you can test different configuration scenarios:

Test Session-Level Configurations:

# Start server without enforcement
npm run dev -- --fmp-token=your_api_key

# Test dynamic mode session
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

# Test static mode session
CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

Test Server-Level Enforcement:

# Start with server-level dynamic mode
npm run dev -- --fmp-token=your_api_key --dynamic-tool-discovery

# ALL sessions will use dynamic mode regardless of session config
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

Running Tests

The project uses Vitest for testing. You can run tests in several ways:

# Run tests in watch mode (for development)
npm test

# Run tests once
npm run test:run

# Run tests with coverage report
npm run test:coverage

The coverage report will be generated in the coverage/ directory and displayed in the terminal. You can open coverage/index.html in your browser to view a detailed HTML coverage report.

Issues and Bug Reports

If you encounter any bugs, have feature requests, or need help with the project, please open an issue on GitHub:

📝 Open an Issue

When reporting issues, please include:

A clear description of the problem or feature request
Steps to reproduce the issue (if applicable)
Your environment details (Node.js version, operating system)
Any relevant error messages or logs
Expected vs. actual behavior

This helps us understand and resolve issues more quickly.

License

This project is licensed under Apache License Version 2.0

Financial Modeling Prep MCP (Model Context Protocol) Server

A Model Context Protocol (MCP) implementation for Financial Modeling Prep, enabling AI assistants to access and analyze financial data, stock information, company fundamentals, and market insights.

Server Architecture
Configuration & Mode Enforcement
- Server Modes
- Configuration Precedence
Usage
Making HTTP Requests
- Session Configuration
- Request Examples
Selective Tool Loading
Dynamic Toolset Management (BETA)
Available Tools
Obtaining a Financial Modeling Prep Access Token
Contributing
- Development Setup
- Running Tests
Issues and Bug Reports
License

Features

Comprehensive Coverage: Access to 253+ financial tools across 24 categories
Tool Set Filtering: Load only the tools you need to reduce complexity and improve performance
Real-time Data: Live stock quotes, market data, and financial information
Financial Statements: Income statements, balance sheets, cash flow statements, and financial ratios
Market Analysis: Technical indicators, analyst estimates, and market performance metrics
Economic Data: Treasury rates, economic indicators, and macroeconomic information
Alternative Data: ESG scores, insider trading, congressional trading, and social sentiment

Server Architecture

Key Features:

Client-level Caching: Exactly one McpServer/DynamicToolsetManager is maintained per clientId. Tokenless requests use a per-request anonymous id (no reuse).
Session Isolation: Sessions are managed by the SDK, but caching does not use sessionId.
Stateful Management: Sessions maintain their state across multiple requests
Mode Enforcement: Server-level configurations can override session-level settings
HTTP-based Protocol: Communicates via HTTP with JSON-RPC formatted messages
Dynamic Tool Management: Tools can be loaded/unloaded at runtime per session

Request Flow:

Client Request → HTTP POST to /mcp endpoint
Session Management → Server creates or retrieves session based on config (caching and reuse are keyed by clientId)
Mode Resolution → Server determines operational mode (Dynamic/Static/Legacy)
Tool Registration → Session-specific tools are loaded based on resolved mode
Request Processing → MCP request is processed with available tools
Response → JSON-RPC response sent back to client

Configuration & Mode Enforcement

The server supports multiple configuration methods with a clear precedence hierarchy to ensure predictable behavior.

Server Modes

The server operates in one of three modes:

🔀 Dynamic Mode (DYNAMIC_TOOL_DISCOVERY=true)
- Starts with only 3 meta-tools: enable_toolset, disable_toolset, get_toolset_status
- Tools loaded on-demand via meta-tool calls
- Best for: Flexible, task-specific workflows where tool requirements change
🔧 Static Mode (FMP_TOOL_SETS=search,company,quotes)
- Pre-loads specific toolsets at session creation
- All specified tools available immediately
- Best for: Known, consistent tool requirements with predictable usage patterns
📚 Legacy Mode (default, no specific configuration)
- Loads all 253+ tools at session creation
- Maximum compatibility with all features available
- Best for: Full feature access without configuration complexity

Configuration Precedence

The server follows a strict precedence hierarchy when determining the operational mode:

🥇 CLI Arguments (highest priority)
   ↓
🥈 Environment Variables
   ↓
🥉 Session Configuration (lowest priority)

⚠️ Important Mode Enforcement Behavior

Example Override Scenario:

# Server started with CLI argument
npm run dev -- --dynamic-tool-discovery

# ALL session requests will use Dynamic Mode, regardless of session config
# Session config like {"FMP_TOOL_SETS": "search,company"} will be IGNORED

Configuration Methods:

CLI Arguments (Server-level - overrides everything)

npm run dev -- --fmp-token=TOKEN --dynamic-tool-discovery
npm run dev -- --fmp-token=TOKEN --fmp-tool-sets=search,company,quotes
npm run dev -- --port=4000 --fmp-token=TOKEN

Environment Variables (Server-level - overrides session configs)

DYNAMIC_TOOL_DISCOVERY=true npm run dev
FMP_TOOL_SETS=search,company,quotes npm run dev

Session Configuration (Session-level - via HTTP query parameter)

# Base64 encoded JSON config in query parameter
curl -X POST "http://localhost:8080/mcp?config=eyJEWU5BTUlDX1RPT0xfRElTQ09WRVJZIjoidHJ1ZSJ9"

⚠️ Configuration Warnings

Server-level modes are GLOBAL: They affect all sessions on the server instance
Session configs are IGNORED when server-level modes are active
No mixing: You cannot have different modes for different sessions when server-level enforcement is active
Restart required: Changing server-level configurations requires server restart

Selective Tool Loading

Available Tool Sets

Tool Set	Description	Example Tools
`search`	Search & Directory	Search stocks, company lookup, symbol directories
`company`	Company Profile & Info	Company profiles, executives, employee count
`quotes`	Real-time Quotes	Live stock prices, market data, price changes
`statements`	Financial Statements	Income statements, balance sheets, cash flow, ratios
`calendar`	Financial Calendar	Earnings calendar, dividends, IPOs, stock splits
`charts`	Price Charts & History	Historical prices, technical charts, market movements
`news`	Financial News	Market news, press releases, financial articles
`analyst`	Analyst Coverage	Price targets, ratings, analyst estimates
`market-performance`	Market Performance	Sector performance, gainers, losers, most active
`insider-trades`	Insider Trading	Corporate insider activity, ownership changes
`institutional`	Institutional Holdings	13F filings, fund holdings, institutional ownership
`indexes`	Market Indexes	S&P 500, NASDAQ, Dow Jones, index constituents
`economics`	Economic Data	Treasury rates, GDP, inflation, economic indicators
`crypto`	Cryptocurrency	Crypto prices, market data, digital assets
`forex`	Foreign Exchange	Currency pairs, exchange rates, forex data
`commodities`	Commodities	Gold, oil, agricultural products, futures
`etf-funds`	ETFs & Mutual Funds	Fund holdings, performance, fund information
`esg`	ESG & Sustainability	Environmental, social, governance ratings
`technical-indicators`	Technical Indicators	RSI, SMA, EMA, MACD, Bollinger Bands
`senate`	Government Trading	Congressional and Senate trading disclosures
`sec-filings`	SEC Filings	10-K, 10-Q, 8-K filings, regulatory documents
`earnings`	Earnings & Transcripts	Earnings reports, call transcripts
`dcf`	DCF Valuation	Discounted cash flow models, valuations
`bulk`	Bulk Data	Large-scale data downloads for analysis

Dynamic Toolset Management (BETA)

🚧 This feature is currently in BETA. API and behavior may change in future versions.

How It Works

When dynamic toolset management is enabled, each session starts with only 3 meta-tools:

enable_toolset - Enable a specific toolset during runtime
disable_toolset - Disable a previously enabled toolset
get_toolset_status - Check which toolsets are currently active

AI assistants can then use these meta-tools to dynamically load and unload specific tool categories as needed for different tasks within their session.

Configuration Options

Server-Level Configuration (Affects All Sessions)

Command Line Arguments:

# Enable dynamic toolset management for all sessions
npm run dev -- --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

# Production deployment
node dist/index.js --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

Environment Variables:

# Set environment variable
export DYNAMIC_TOOL_DISCOVERY=true
export FMP_ACCESS_TOKEN=YOUR_TOKEN
npm run dev

# Or inline
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=YOUR_TOKEN npm start

Docker:

# docker-compose.yml
version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    environment:
      - FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
      - DYNAMIC_TOOL_DISCOVERY=true # Enable for all sessions

Session-Level Configuration (When No Server Override)

When no server-level dynamic mode is set, individual sessions can request dynamic mode:

# Base64 encode: {"DYNAMIC_TOOL_DISCOVERY":"true"}
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

Example Workflow

Start server with dynamic mode:
```
DYNAMIC_TOOL_DISCOVERY=true npm start
```

AI assistant initializes session and gets meta-tools:

// Response includes only 3 meta-tools:
{
  "tools": [
    { "name": "enable_toolset", "description": "Enable a specific toolset" },
    { "name": "disable_toolset", "description": "Disable a toolset" },
    { "name": "get_toolset_status", "description": "Check active toolsets" }
  ]
}

AI assistant enables needed toolsets:

// Enable search toolset
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"enable_toolset","arguments":{"toolset":"search"}}}

// Enable quotes toolset
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"enable_toolset","arguments":{"toolset":"quotes"}}}

AI assistant uses the enabled tools:

// Now can use search and quotes tools
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"searchSymbol","arguments":{"query":"AAPL"}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"getQuote","arguments":{"symbol":"AAPL"}}}

AI assistant can disable unused toolsets:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "disable_toolset",
    "arguments": { "toolset": "search" }
  }
}

Benefits

Performance: Start faster with fewer tools loaded initially per session
Flexibility: Load only the tools needed for current tasks
Resource Efficiency: Reduce memory usage by disabling unused toolsets per session
Task-Oriented: Perfect for AI assistants that work on specific financial analysis tasks
Session Isolation: Each session can have different active toolsets

Usage

Registries

For production environments, you can use this MCP server through various registries that provide hosted and managed MCP servers:

Smithery.ai

🚀 View on Smithery.ai

Smithery is a platform that helps developers find and ship AI-native services designed to communicate with AI agents. All services follow the Model Context Protocol (MCP) specification and provide:

Centralized discovery of MCP servers
Hosting and distribution for MCP servers
Standardized interfaces for tool integration

Session Configuration with Smithery

When using Smithery, you can configure individual sessions by passing configuration in your MCP client. The Smithery platform handles the HTTP request formatting and session management.

Example configurations for Smithery:

// Dynamic mode session
{
  "DYNAMIC_TOOL_DISCOVERY": "true"
}

// Static mode session
{
  "FMP_TOOL_SETS": "search,company,quotes"
}

// Legacy mode (all tools)
{}

For detailed integration instructions, follow the Smithery documentation for connecting MCP clients to hosted servers.

Glama.ai

Use on Glama.ai

Contexaai.com

Use on Contexaai.com

HTTP Server & Local Development

The server runs as an HTTP server that exposes a Model Context Protocol endpoint. Each request can include session-specific configuration via query parameters.

Basic Server Setup

Local Development:

# Clone and setup
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server
npm install
npm run build

# Run in development
FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

# Or with CLI arguments
npm run dev -- --fmp-token=YOUR_TOKEN
npm run dev -- --port=4000 --fmp-token=YOUR_TOKEN

Server-Level Mode Configuration

🔐 Server-Level Dynamic Mode (All Sessions Use Dynamic Mode):

# CLI argument (highest priority)
npm run dev -- --fmp-token=YOUR_TOKEN --dynamic-tool-discovery

# Environment variable
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

🔧 Server-Level Static Mode (All Sessions Use Specified Toolsets):

# CLI argument (highest priority)
npm run dev -- --fmp-token=YOUR_TOKEN --fmp-tool-sets=search,company,quotes

# Environment variable
FMP_TOOL_SETS=search,company,quotes FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

📚 Server-Level Legacy Mode (All Sessions Get All Tools):

# Default behavior - no specific configuration
npm run dev -- --fmp-token=YOUR_TOKEN
FMP_ACCESS_TOKEN=YOUR_TOKEN npm run dev

Custom Port Configuration

# Change server port via environment variable
PORT=4000 npm run dev -- --fmp-token=YOUR_TOKEN

# Change server port via CLI argument
npm run dev -- --port=4000 --fmp-token=YOUR_TOKEN

Docker Usage

Docker deployment supports all configuration methods with proper environment variable handling.

Using Docker with Environment Variables

# Basic deployment
docker run -p 8080:8080 -e FMP_ACCESS_TOKEN=YOUR_TOKEN your-image-name

# With server-level dynamic mode
docker run -p 8080:8080 \
  -e FMP_ACCESS_TOKEN=YOUR_TOKEN \
  -e DYNAMIC_TOOL_DISCOVERY=true \
  your-image-name

# With server-level static mode
docker run -p 8080:8080 \
  -e FMP_ACCESS_TOKEN=YOUR_TOKEN \
  -e FMP_TOOL_SETS=search,company,quotes \
  your-image-name

Using Docker Compose

Create a docker-compose.yml file:

version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    environment:
      - FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
      - PORT=8080
      # Optional: Server-level mode enforcement
      - DYNAMIC_TOOL_DISCOVERY=true # All sessions use dynamic mode
      # OR
      - FMP_TOOL_SETS=search,company,quotes # All sessions use these toolsets
      # OR leave both unset for legacy mode (all tools)

Then run:

docker-compose up

Using .env File with Docker Compose

Create a .env file:

FMP_ACCESS_TOKEN=YOUR_FMP_ACCESS_TOKEN
PORT=8080

# Optional: Choose ONE server-level mode
DYNAMIC_TOOL_DISCOVERY=true
# OR
# FMP_TOOL_SETS=search,company,quotes
# OR leave both commented for legacy mode

And reference it in your docker-compose.yml:

version: "3.8"
services:
  fmp-mcp:
    image: your-image-name
    ports:
      - "8080:8080"
    env_file:
      - .env

Example System Prompts

The following system prompts are designed to help AI assistants effectively use this MCP server for financial analysis tasks. Choose the appropriate prompt based on your server configuration mode.

For Dynamic Toolset Mode

You are an expert financial analyst AI with access to comprehensive market data tools.

CORE RULES:
- Always use tools for current market data; never rely on outdated information or estimates
- Check conversation history to avoid redundant tool calls
- Provide concise, data-driven responses
- Always include: "This is not financial advice"

DYNAMIC TOOLSET MANAGEMENT:
Your tools are organized into categories ("toolsets") that must be enabled before use. You have a 4-toolset maximum at any time.

Available toolsets: search, company, quotes, statements, calendar, charts, news, analyst, market-performance, insider-trades, institutional, indexes, economics, crypto, forex, commodities, etf-funds, esg, technical-indicators, senate, sec-filings, earnings, dcf, bulk

EXECUTION WORKFLOW:
1. ENABLE: Use enable_toolset for required categories based on the user's query
2. VERIFY: Call get_toolset_status to confirm active toolsets. If >4 active, use disable_toolset to remove the least relevant
3. EXECUTE: Call specific tools from enabled toolsets
4. CLEAN UP: Consider disabling unused toolsets when switching to different analysis types

FAILURE PROTOCOL:
If tools fail repeatedly or data is unavailable, state: "I cannot find the requested information with the available tools" and stop attempting.

Begin each analysis by enabling the appropriate toolsets for the user's request.

For Static Toolset Mode

You are an expert financial analyst AI with access to comprehensive market data tools.

CORE RULES:
- Always use tools for current market data; never rely on outdated information or estimates
- Check conversation history to avoid redundant tool calls
- Provide concise, data-driven responses
- Always include: "This is not financial advice"

STATIC TOOLSET CONFIGURATION:
Your tools are pre-loaded and immediately available. All configured toolsets remain active throughout the session.

EXECUTION WORKFLOW:
1. IDENTIFY: Determine which tools from your available toolsets best address the user's query
2. EXECUTE: Call the appropriate tools directly - no toolset management needed
3. ANALYZE: Process the data and provide insights based on the results

TOOL CATEGORIES:
Your available tools span multiple categories including company profiles, financial statements, market quotes, technical analysis, news sentiment, and economic indicators. Use the most relevant tools for each analysis.

FAILURE PROTOCOL:
If tools fail repeatedly or data is unavailable, state: "I cannot find the requested information with the available tools" and stop attempting.

Proceed directly to analysis using your available tools based on the user's request.

Usage Tips

Dynamic Mode: Best for exploratory analysis where tool requirements change frequently. The AI assistant will manage toolsets based on the current task.
Static Mode: Best for consistent, predictable workflows where the same types of analysis are performed repeatedly.
Legacy Mode: Use the Static Mode prompt when all tools are pre-loaded (default configuration).

Human-Friendly Capabilities Prompt

This server provides a human-friendly prompt to list capabilities in one shot.

Name: list_mcp_assets
Output sections: Server Capabilities, Prompts, Tools (mode-aware), Resources (health snapshot), Quick Start
Exposed only as an MCP prompt (no tool alias)

List assets via prompts

# 1) Initialize (example: dynamic mode session)
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": { "protocolVersion": "2024-11-05", "clientInfo": {"name": "client", "version": "1.0.0"}, "capabilities": {} }
  }'

# 2) List prompts
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"prompts/list","params":{}}'

# 3) Get the capabilities prompt
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get","params":{"name":"list_mcp_assets","arguments":{}}}'

Notes:

The Tools section adapts to the effective mode (Dynamic/Static/Legacy). In legacy mode, it summarizes categories instead of listing all 250+ tools.
In Static mode, toolsets shown are the authoritative list from the server’s mode enforcer (single source of truth). Session FMP_TOOL_SETS may request Static mode, but server-level configuration controls the final toolsets.
The Resources section includes a lightweight health snapshot (uptime, memory summary, version, mode).

Making HTTP Requests

The server exposes a Model Context Protocol endpoint at /mcp that accepts JSON-RPC formatted requests. Each request can include optional session configuration via query parameters.

Endpoint Format

POST http://localhost:8080/mcp[?config=BASE64_ENCODED_CONFIG]

Required Headers

Content-Type: application/json
Accept: application/json, text/event-stream

Session Configuration

Configuration Examples:

Dynamic Mode Session:

# Configuration: {"DYNAMIC_TOOL_DISCOVERY":"true"}
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
# Result: eyJEWU5BTUlDX1RPT0xfRElTQ09WRVJZIjoidHJ1ZSJ9

Static Mode Session:

# Configuration: {"FMP_TOOL_SETS":"search,company,quotes"}
CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,company,quotes"}' | base64)
# Result: eyJGTVBfVE9PTF9TRVRTIjoic2VhcmNoLGNvbXBhbnkscXVvdGVzIn0=

Legacy Mode Session:

# Configuration: {} (empty object)
CONFIG_BASE64=$(echo -n '{}' | base64)
# Result: e30=

Request Examples

1. Initialize a Dynamic Mode Session

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "fmp-mcp-server",
      "version": "1.0.0"
    }
  }
}

2. List Available Tools

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Expected Response (Dynamic Mode):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "enable_toolset",
        "description": "Enable a specific toolset during runtime",
        "inputSchema": {
          "type": "object",
          "properties": {
            "toolset": {
              "type": "string",
              "description": "Name of the toolset to enable"
            }
          },
          "required": ["toolset"]
        }
      },
      {
        "name": "disable_toolset",
        "description": "Disable a previously enabled toolset"
      },
      {
        "name": "get_toolset_status",
        "description": "Check which toolsets are currently active"
      }
    ]
  }
}

3. Enable a Toolset (Dynamic Mode)

CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "enable_toolset",
      "arguments": {
        "toolset": "search"
      }
    }
  }'

4. Call a Financial Tool

CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "searchSymbol",
      "arguments": {
        "query": "Apple"
      }
    }
  }'

5. Get Stock Quote

CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "getQuote",
      "arguments": {
        "symbol": "AAPL"
      }
    }
  }'

Session and Client Behavior

Session Persistence: Each unique config parameter creates a separate session (SDK-managed)
Tool State: In dynamic mode, enabled/disabled toolsets may be reused for the same clientId across requests
Isolation: Sessions don't interfere with each other's tool configurations; caching is keyed by clientId
Caching: Client storage (LRU + TTL) maintains one McpServer/DynamicToolsetManager per clientId

Cache Reuse Policy (Session-Config Aware)

For the same clientId (derived from token), the server compares each request’s desired mode and static tool sets against the cached instance.
If there is a difference and there is NO server-level mode enforcement, a new McpServer instance is created and the cache entry is replaced.
If a server-level mode is enforced (via CLI/env), session-level changes are ignored and the cached instance is reused.
Static tool set comparison is order-insensitive (e.g., search,company equals company,search).

Error Handling

Common error responses:

// Invalid configuration
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Bad Request: Invalid configuration"
  },
  "id": null
}

// Tool not available
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Tool not found: toolName"
  },
  "id": 1
}

// Missing required parameters
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Missing required parameter: symbol"
  },
  "id": 2
}

Available Tools

⚠️ Important: Mode Enforcement Behavior

Server-Level Configurations Override Session Configurations:

When CLI arguments (--dynamic-tool-discovery, --fmp-tool-sets) are used, they apply to ALL sessions

When environment variables (DYNAMIC_TOOL_DISCOVERY, FMP_TOOL_SETS) are set, they apply to ALL sessions

Session-level configurations via query parameters are IGNORED when server-level modes are active

This ensures consistent behavior across all sessions on a server instance

Configuration Precedence: CLI Arguments > Environment Variables > Session Configuration

Example: If server started with --dynamic-tool-discovery, ALL sessions will use dynamic mode even if they request {"FMP_TOOL_SETS":"search,company"} in their session config.

This MCP provides the following tools for AI assistants to access financial data:

Search Tools

searchSymbol: Search for stock symbols by name or ticker
searchName: Search for companies by name
searchCIK: Search for companies by CIK number
searchCUSIP: Search for securities by CUSIP number
searchISIN: Search for securities by ISIN number
stockScreener: Screen stocks based on various criteria
searchExchangeVariants: Search for symbol variants across different exchanges
searchCompaniesByName: Search for companies by name
searchCompaniesBySymbol: Search for companies by symbol
searchCompaniesByCIK: Search for companies by CIK number

Directory and Symbol Lists

getCompanySymbols: Get a list of all company symbols
getFinancialStatementSymbols: Get a list of companies with available financial statements
getCIKList: Get a list of CIK numbers for SEC-registered entities
getSymbolChanges: Get a list of stock symbol changes
getETFList: Get a list of ETFs
getActivelyTradingList: Get a list of actively trading companies
getEarningsTranscriptList: Get a list of companies with earnings transcripts
getAvailableExchanges: Get a list of available exchanges
getAvailableSectors: Get a list of available sectors
getAvailableIndustries: Get a list of available industries
getAvailableCountries: Get a list of available countries
getAvailableTranscriptSymbols: Get a list of symbols with available transcripts
getAllIndustryClassification: Get all industry classifications
getIndustryClassificationList: Get a list of industry classifications

Financial Statements

getIncomeStatement: Get company income statements
getBalanceSheet: Get company balance sheet statements
getBalanceSheetStatement: Get company balance sheet statements
getCashFlowStatement: Get company cash flow statements
getIncomeStatementAsReported: Get income statements as reported
getBalanceSheetAsReported: Get balance sheet statements as reported
getBalanceSheetStatementAsReported: Get balance sheet statements as reported
getCashFlowStatementAsReported: Get cash flow statements as reported
getFullFinancialStatementAsReported: Get full financial statements as reported
getFinancialStatementFullAsReported: Get full financial statements as reported
getFinancialReportDates: Get dates of available financial reports
getFinancialReportsDates: Get dates of available financial reports
getLatestFinancialStatements: Get latest financial statements
getIncomeStatementTTM: Get trailing twelve months income statements
getBalanceSheetStatementTTM: Get trailing twelve months balance sheet statements
getCashFlowStatementTTM: Get trailing twelve months cash flow statements
getIncomeStatementGrowth: Get income statement growth
getBalanceSheetStatementGrowth: Get balance sheet statement growth
getCashFlowStatementGrowth: Get cash flow statement growth
getFinancialStatementGrowth: Get financial statement growth
getFinancialReportJSON: Get financial report in JSON format
getFinancialReportXLSX: Get financial report in XLSX format
getRevenueProductSegmentation: Get revenue product segmentation
getRevenueGeographicSegmentation: Get revenue geographic segmentation

Financial Metrics and Analysis

getKeyMetrics: Get key financial metrics for a company
getKeyMetricsTTM: Get key metrics for trailing twelve months
getRatios: Get financial ratios for a company
getFinancialRatios: Get financial ratios for a company
getFinancialRatiosTTM: Get financial ratios for trailing twelve months
getFinancialGrowth: Get financial growth metrics
getIncomeStatementGrowth: Get income statement growth metrics
getBalanceSheetGrowth: Get balance sheet growth metrics
getCashFlowStatementGrowth: Get cash flow statement growth metrics
getDCFValuation: Get DCF (Discounted Cash Flow) valuation for a stock
getLeveredDCFValuation: Get levered DCF valuation for a stock
calculateCustomDCF: Calculate custom DCF valuation with user-defined parameters
calculateCustomLeveredDCF: Calculate custom levered DCF valuation with user-defined parameters
getEnterpriseValue: Get enterprise value for a company
getFinancialScore: Get financial score for a company
getFinancialScores: Get financial scores for a company
getOwnerEarnings: Get owner earnings for a company

Technical Indicators

getSMA: Get Simple Moving Average (SMA) indicator
getEMA: Get Exponential Moving Average (EMA) indicator
getWMA: Get Weighted Moving Average (WMA) indicator
getDEMA: Get Double Exponential Moving Average (DEMA) indicator
getTEMA: Get Triple Exponential Moving Average (TEMA) indicator
getWilliams: Get Williams %R indicator
getADX: Get Average Directional Index (ADX) indicator
getStandardDeviation: Get Standard Deviation indicator
getRSI: Get Relative Strength Index (RSI) indicator

Quotes and Price Data

getQuote: Get current stock quote information
getBatchQuotes: Get quotes for multiple symbols
getQuoteShort: Get abbreviated stock quote information
getBatchQuotesShort: Get abbreviated quotes for multiple symbols
getHistoricalPrice: Get historical price data
getHistoricalPriceChart: Get historical price chart data
getHistoricalDailyPrice: Get historical daily price data
getHistoricalStockSplits: Get historical stock splits
getHistoricalDividends: Get historical dividends
getTechnicalIndicator: Get technical indicators for a stock
getLightChart: Get light version of price chart
getFullChart: Get full version of price chart
getUnadjustedChart: Get unadjusted price chart
getDividendAdjustedChart: Get dividend-adjusted price chart
getIntradayChart: Get intraday price chart
getAftermarketQuote: Get aftermarket quote
getAftermarketTrade: Get aftermarket trade data
getBatchAftermarketQuote: Get batch aftermarket quotes
getBatchAftermarketTrade: Get batch aftermarket trade data
getStockPriceChange: Get stock price change information

Market Indexes and Performance

getIndexList: Get a list of all market indexes
getIndexQuotes: Get quotes for market indexes
getIndexQuote: Get quote for a specific index
getIndexShortQuote: Get abbreviated quote for an index
getAllIndexQuotes: Get quotes for all market indexes
getSP500Constituents: Get S&P 500 constituent companies
getHistoricalSP500Changes: Get historical S&P 500 changes
getNasdaqConstituents: Get NASDAQ constituent companies
getDowJonesConstituents: Get Dow Jones constituent companies
getHistoricalNasdaqChanges: Get historical NASDAQ changes
getHistoricalDowJonesChanges: Get historical Dow Jones changes
getSectorPerformance: Get sector performance data
getHistoricalSectorPerformance: Get historical sector performance
getBiggestGainers: Get biggest gaining stocks
getBiggestLosers: Get biggest losing stocks
getMostActiveStocks: Get most active stocks
getHistoricalIndexFullChart: Get historical index full chart
getHistoricalIndexLightChart: Get historical index light chart
getIndex1MinuteData: Get 1-minute index data
getIndex5MinuteData: Get 5-minute index data
getIndex1HourData: Get 1-hour index data
getSectorPerformanceSnapshot: Get sector performance snapshot
getSectorPESnapshot: Get sector PE ratio snapshot
getIndustryPerformanceSnapshot: Get industry performance snapshot
getIndustryPerformanceSummary: Get industry performance summary
getIndustryPESnapshot: Get industry PE ratio snapshot
getHistoricalIndustryPerformance: Get historical industry performance
getHistoricalIndustryPE: Get historical industry PE ratios
getHistoricalSectorPE: Get historical sector PE ratios

Market Data

getMarketHours: Get market hours for a specific exchange
getExchangeMarketHours: Get market hours for a specific exchange
getHolidaysByExchange: Get holidays for a specific exchange with optional date range filtering
getAllExchangeMarketHours: Get market hours for all exchanges
getEarningsCalendar: Get earnings announcement calendar
getIPOCalendar: Get initial public offering calendar
getStockSplitCalendar: Get stock split calendar
getDividendCalendar: Get dividend calendar
getEconomicCalendar: Get economic events calendar
getIPODisclosures: Get IPO disclosures
getIPOProspectuses: Get IPO prospectuses

News and Press Releases

getFMPArticles: Get financial news articles from FMP
getGeneralNews: Get general financial news
getStockNews: Get news for specific stocks
getStockNewsSentiment: Get news with sentiment analysis
getPressReleases: Get company press releases
searchStockNews: Search stock news
searchPressReleases: Search press releases
getCryptoNews: Get cryptocurrency news
searchCryptoNews: Search cryptocurrency news
getForexNews: Get forex news
searchForexNews: Search forex news

SEC Filings

getLatestFinancialFilings: Get latest financial filings
getFilingsBySymbol: Get filings by symbol
getFilingsByCIK: Get filings by CIK
getFilingsByFormType: Get filings by form type
getLatest8KFilings: Get latest 8-K filings
getSecFilingExtract: Get SEC filing extract
getFilingExtractAnalyticsByHolder: Get filing extract analytics by holder

Insider and Institutional Trading

getInsiderTrading: Get insider trading data
getInsiderRoster: Get insider roster for a company
getInsiderRosterStatistics: Get statistics on insider roster
getInsiderTransactionTypes: Get types of insider transactions
getInsiderOwnership: Get insider ownership information
getInstitutionalOwnership: Get institutional ownership data
getInstitutionalHolders: Get institutional holders for a company
getInstitutionalHoldersList: Get list of institutional holders
getInstitutionalHolderPortfolioDates: Get portfolio dates for institutional holders
get13FFilings: Get 13F filings
get13FDates: Get dates of 13F filings
getForm13FFilingDates: Get 13F filing dates
getLatestInsiderTrading: Get latest insider trading data
searchInsiderTrades: Search insider trades
searchInsiderTradesByReportingName: Search insider trades by reporting name
getInsiderTradeStatistics: Get insider trade statistics
getLatestInstitutionalFilings: Get latest institutional filings
getHolderPerformanceSummary: Get holder performance summary
getHolderIndustryBreakdown: Get holder industry breakdown
getPositionsSummary: Get positions summary

ETFs and Funds

getETFHolder: Get ETF holder information
getETFSectorWeighting: Get ETF sector weightings
getETFCountryWeighting: Get ETF country weightings
getETFExposure: Get ETF exposure to stocks
getFundInfo: Get fund information
getFundHolder: Get fund holder information
getFundSectorWeighting: Get fund sector weightings
getFundHoldings: Get fund holdings
getFundCountryAllocation: Get fund country allocation
getFundAssetExposure: Get fund asset exposure
getDisclosure: Get latest fund disclosure holders information
getFundDisclosure: Get comprehensive fund disclosure data by year/quarter
searchFundDisclosures: Search fund disclosures by holder name
getFundDisclosureDates: Get fund disclosure dates (with optional CIK)
getETFHoldersBulk: Get ETF holders in bulk
getETFQuotes: Get ETF quotes
getMutualFundQuotes: Get mutual fund quotes

Government Trading

getGovernmentTradingList: Get government trading list
getSenateTrading: Get senate trading data
getHouseTrading: Get house trading data
getSenateTrades: Get senate trades
getSenateTradesByName: Get senate trades by name
getHouseTrades: Get house trades
getHouseTradesByName: Get house trades by name
getLatestSenateDisclosures: Get latest senate disclosures
getLatestHouseDisclosures: Get latest house disclosures

Cryptocurrency and Forex

getCryptocurrencyList: Get a list of cryptocurrencies
getCryptocurrencyQuote: Get cryptocurrency quote
getCryptocurrencyShortQuote: Get abbreviated cryptocurrency quote
getCryptocurrencyBatchQuotes: Get quotes for multiple cryptocurrencies
getCryptocurrencyHistoricalLightChart: Get light historical cryptocurrency chart
getCryptocurrencyHistoricalFullChart: Get full historical cryptocurrency chart
getCryptocurrency1MinuteData: Get 1-minute cryptocurrency data
getCryptocurrency5MinuteData: Get 5-minute cryptocurrency data
getCryptocurrency1HourData: Get 1-hour cryptocurrency data
getForexList: Get a list of forex pairs
getForexQuote: Get forex pair quote
getForexShortQuote: Get abbreviated forex quote
getForexBatchQuotes: Get quotes for multiple forex pairs with optional short format
getForexHistoricalLightChart: Get light historical forex chart with optional date range
getForexHistoricalFullChart: Get full historical forex chart with optional date range
getForex1MinuteData: Get 1-minute forex data with optional date range
getForex5MinuteData: Get 5-minute forex data with optional date range
getForex1HourData: Get 1-hour forex data with optional date range

Earnings

getEarningsReports: Get earnings reports
getEarningsTranscript: Get earnings transcript
getEarningsTranscriptDates: Get earnings transcript dates
getLatestEarningsTranscripts: Get latest earnings transcripts
getEarningsSurprisesBulk: Get bulk earnings surprises

Special Data Sets

getCOTList: Get Commitment of Traders (COT) list
getCOTReports: Get COT reports for a specific symbol with optional date range filtering
getCOTAnalysis: Get COT analysis for a specific symbol with optional date range filtering
getGovernmentTradingList: Get government trading list
getSenateTrading: Get senate trading data
getHouseTrading: Get house trading data
getESGDisclosures: Get ESG disclosures for a specific symbol
getESGRatings: Get ESG ratings for a specific symbol
getESGBenchmarks: Get ESG benchmark data with optional year filtering

Commodities

listCommodities: Get a list of all available commodities with their symbols, names, exchanges, trade months, and currencies

Economics

getTreasuryRates: Get treasury rates with optional date range filtering
getEconomicIndicators: Get economic indicators by name with optional date range filtering
getEconomicCalendar: Get economic events calendar with optional date range filtering
getMarketRiskPremium: Get market risk premium data

Fundraisers

getLatestCrowdfundingCampaigns: Get latest crowdfunding campaigns
searchCrowdfundingCampaigns: Search crowdfunding campaigns
getCrowdfundingCampaignsByCIK: Get crowdfunding campaigns by CIK
getLatestEquityOfferings: Get latest equity offerings
searchEquityOfferings: Search equity offerings
getEquityOfferingsByCIK: Get equity offerings by CIK

Bulk Data Tools

getCompanyProfilesBulk: Get bulk company profiles (CSV format)
getStockRatingsBulk: Get bulk stock ratings (CSV format)
getDCFValuationsBulk: Get bulk DCF valuations (CSV format)
getFinancialScoresBulk: Get bulk financial scores (CSV format)
getPriceTargetSummariesBulk: Get bulk price target summaries (CSV format)
getUpgradesDowngradesConsensusBulk: Get bulk upgrades/downgrades consensus (CSV format)
getKeyMetricsTTMBulk: Get bulk key metrics TTM (CSV format)
getRatiosTTMBulk: Get bulk ratios TTM (CSV format)
getStockPeersBulk: Get bulk stock peers (CSV format)
getEODDataBulk: Get bulk end-of-day price data (CSV format)
getIncomeStatementsBulk: Get bulk income statements (CSV format)
getIncomeStatementGrowthBulk: Get bulk income statement growth data (CSV format)
getBalanceSheetStatementsBulk: Get bulk balance sheet statements (CSV format)
getBalanceSheetGrowthBulk: Get bulk balance sheet growth data (CSV format)
getCashFlowStatementsBulk: Get bulk cash flow statements (CSV format)
getCashFlowGrowthBulk: Get bulk cash flow growth data (CSV format)
getFinancialRatiosBulk: Get bulk financial ratios (CSV format)
getKeyMetricsBulk: Get bulk key metrics (CSV format)
getFinancialGrowthBulk: Get bulk financial growth data (CSV format)

Obtaining a Financial Modeling Prep Access Token

To get a Financial Modeling Prep access token:

Visit the Financial Modeling Prep website
Click on "Sign Up" to create an account
Verify your email address
After signing in, navigate to your Dashboard to find your API key
For more data access, consider upgrading to a paid plan (Starter, Premium, Ultimate, or Enterprise)

Financial Modeling Prep offers different pricing tiers with varying levels of data access and API call limits. For more information, visit the FMP Pricing page.

Contributing

Contributions are welcome! Here's how you can contribute:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Every pull request triggers a GitHub Actions workflow that verifies the build process.

Development Setup

# Clone the repository
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with your API key
FMP_ACCESS_TOKEN=your_api_key npm run dev

# Or specify the API key directly via CLI argument
npm run dev -- --fmp-token=your_api_key

The development server will start on port 8080 by default. You can configure the port using the PORT environment variable:

PORT=4000 FMP_ACCESS_TOKEN=your_api_key npm run dev

Development with Server-Level Mode Enforcement

Server-Level Static Mode (All Sessions Use Specific Toolsets):

# Environment variable approach
FMP_TOOL_SETS=search,company,quotes FMP_ACCESS_TOKEN=your_api_key npm run dev

# CLI argument approach (higher precedence)
npm run dev -- --fmp-token=your_api_key --fmp-tool-sets=search,company,quotes

Server-Level Dynamic Mode (All Sessions Start with Meta-Tools):

# Environment variable approach
DYNAMIC_TOOL_DISCOVERY=true FMP_ACCESS_TOKEN=your_api_key npm run dev

# CLI argument approach (higher precedence)
npm run dev -- --fmp-token=your_api_key --dynamic-tool-discovery

Session-Level Configuration (Default - No Server Enforcement):

# Start server without mode enforcement
npm run dev -- --fmp-token=your_api_key

# Individual sessions can then specify their own configurations via HTTP requests

Testing Different Configurations

When developing, you can test different configuration scenarios:

Test Session-Level Configurations:

# Start server without enforcement
npm run dev -- --fmp-token=your_api_key

# Test dynamic mode session
CONFIG_BASE64=$(echo -n '{"DYNAMIC_TOOL_DISCOVERY":"true"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

# Test static mode session
CONFIG_BASE64=$(echo -n '{"FMP_TOOL_SETS":"search,quotes"}' | base64)
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

Test Server-Level Enforcement:

# Start with server-level dynamic mode
npm run dev -- --fmp-token=your_api_key --dynamic-tool-discovery

# ALL sessions will use dynamic mode regardless of session config
curl -X POST "http://localhost:8080/mcp?config=${CONFIG_BASE64}" -d '...'

Running Tests

The project uses Vitest for testing. You can run tests in several ways:

# Run tests in watch mode (for development)
npm test

# Run tests once
npm run test:run

# Run tests with coverage report
npm run test:coverage

The coverage report will be generated in the coverage/ directory and displayed in the terminal. You can open coverage/index.html in your browser to view a detailed HTML coverage report.

Issues and Bug Reports

If you encounter any bugs, have feature requests, or need help with the project, please open an issue on GitHub:

📝 Open an Issue

When reporting issues, please include:

A clear description of the problem or feature request
Steps to reproduce the issue (if applicable)
Your environment details (Node.js version, operating system)
Any relevant error messages or logs
Expected vs. actual behavior

This helps us understand and resolve issues more quickly.

License

This project is licensed under Apache License Version 2.0

Financial Modeling Prep MCP Server

Financial Modeling Prep MCP (Model Context Protocol) Server

Table of Contents

Features

Server Architecture

Key Features:

Request Flow:

Configuration & Mode Enforcement

Server Modes

Configuration Precedence

⚠️ Important Mode Enforcement Behavior

Configuration Methods:

⚠️ Configuration Warnings

Selective Tool Loading

Available Tool Sets

Dynamic Toolset Management (BETA)

How It Works

Configuration Options

Server-Level Configuration (Affects All Sessions)

Session-Level Configuration (When No Server Override)

Example Workflow

Benefits

Usage

Registries

Smithery.ai

Session Configuration with Smithery

Glama.ai

Contexaai.com

HTTP Server & Local Development

Basic Server Setup

Server-Level Mode Configuration

Custom Port Configuration

Docker Usage

Using Docker with Environment Variables

Using Docker Compose

Using .env File with Docker Compose

Example System Prompts

For Dynamic Toolset Mode

For Static Toolset Mode

Usage Tips

Human-Friendly Capabilities Prompt

List assets via prompts

Making HTTP Requests

Endpoint Format

Required Headers

Session Configuration

Configuration Examples:

Request Examples

1. Initialize a Dynamic Mode Session

2. List Available Tools

3. Enable a Toolset (Dynamic Mode)

4. Call a Financial Tool

5. Get Stock Quote

Session and Client Behavior

Cache Reuse Policy (Session-Config Aware)

Error Handling

Available Tools

Search Tools

Directory and Symbol Lists

Company Information

Financial Statements

Financial Metrics and Analysis

Technical Indicators

Quotes and Price Data

Market Indexes and Performance

Market Data

News and Press Releases

SEC Filings

Insider and Institutional Trading

ETFs and Funds

Government Trading

Cryptocurrency and Forex

Earnings

Special Data Sets

Commodities

Economics

Fundraisers

Bulk Data Tools

Obtaining a Financial Modeling Prep Access Token

Contributing