Related Pages

Related topics: Installation Guide, System Architecture, Quick Start Guide

Overview

The Financial Modeling Prep MCP Server is a Model Context Protocol (MCP) server implementation that exposes 250+ financial data tools to AI assistants through the Financial Modeling Prep (FMP) API. Built on Node.js with the toolception framework and Fastify HTTP server, it provides a bridge between AI assistants and comprehensive financial market data including stocks, ETFs, crypto, forex, commodities, economics, and more.

Source: README.md

Purpose and Scope

The server serves as an intermediary layer that:

1. Translates MCP tool calls into FMP API requests
2. Manages authentication using FMP API tokens
3. Organizes 250+ endpoints into logical tool sets
4. Provides multiple deployment modes for different use cases

The MCP protocol enables AI assistants like Claude to interact with financial data tools using a standardized interface. The FMP API provides underlying market data including real-time quotes, financial statements, SEC filings, insider trading data, and macroeconomic indicators.

Source: CLAUDE.md

Architecture

The server follows a layered architecture with clear separation of concerns:

graph TD
    subgraph "MCP Protocol Layer"
        MCP[MCP Protocol<br/>Client Connection]
    end
    
    subgraph "Toolception Framework"
        Meta[Meta-Tools<br/>Tool Discovery]
        Sets[Tool Set<br/>Management]
    end
    
    subgraph "Tools Layer"
        T1[Quotes Tools]
        T2[Statements Tools]
        T3[SEC Filings Tools]
        TN[...25 more<br/>tool modules]
    end
    
    subgraph "API Client Layer"
        FMP[FMP Client]
        DC[Domain Clients<br/>28 total]
    end
    
    subgraph "External Services"
        FMP_API[Financial Modeling<br/>Prep API]
    end
    
    MCP --> Meta
    MCP --> Sets
    Meta --> T1
    Meta --> T2
    Meta --> T3
    Sets --> TN
    T1 --> FMP
    T2 --> FMP
    T3 --> DC
    TN --> DC
    FMP --> FMP_API
    DC --> FMP_API

Directory Structure

Source: CLAUDE.md

Server Modes

The server supports three operational modes configured at startup:

The mode is determined by the DYNAMIC_TOOL_DISCOVERY environment variable or --dynamic-tool-discovery CLI flag. In Dynamic mode, users can load specific tool sets using meta-tools rather than receiving all tools at once.

Source: README.md Source: CLAUDE.md

Tool Categories

The server exposes 250+ tools organized into 24 categories:

Source: README.md

Configuration Options

Environment Variables

CLI Arguments

Source: server.json

Authentication

The server uses API key authentication where the FMP token is passed as a query parameter to the FMP API (not as HTTP headers). Token precedence follows this order:

1. Context token — Provided per-session by the MCP client
2. Instance token — Set via --fmp-token CLI argument
3. Environment variable — Set via FMP_ACCESS_TOKEN

Source: CLAUDE.md

⚠️ Known Issue: Users have reported difficulty setting the API key via certain registry interfaces (Smithery.ai). The recommended approach is to set FMP_ACCESS_TOKEN as an environment variable or use the --fmp-token CLI argument directly.

Source: Issue #81

Key Invariants

Understanding these fundamental rules is essential for working with the server:

Source: CLAUDE.md

Error Handling Pattern

All tool handlers follow a strict pattern to ensure MCP protocol compatibility:

async function toolHandler(params) {
  try {
    const results = await client.method(params);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
}

Important: Tools must never throw exceptions. The MCP protocol expects errors in the response object, not as thrown exceptions.

Source: src/tools/AGENTS.md

Tool Registration

Tools are registered using the MCP SDK's server.tool() method with Zod schemas for parameter validation:

server.tool(
  "getQuote",
  "Access real-time stock quotes with the FMP Stock Quote API.",
  {
    symbol: z.string().describe("Stock symbol"),
  },
  async ({ symbol }) => {
    // handler implementation
  }
);

Source: src/tools/quotes.ts

Deployment Options

Hosted Instance (Fastest)

Connect directly to the production server without installation:

https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp

Self-Hosted via NPM

npm install -g financial-modeling-prep-mcp-server
fmp-mcp --fmp-token=YOUR_FMP_API_KEY

Self-Hosted via NPX

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

Docker

docker build -t fmp-mcp .
docker run -e FMP_ACCESS_TOKEN=YOUR_FMP_API_KEY -p 3000:3000 fmp-mcp

Source: README.md

Runtime Requirements

Source: package.json

Known Limitations and Issues

Python Reserved Keywords in Parameter Names

Some tool schemas use parameter names that conflict with Python reserved keywords, causing issues with Python-based MCP clients. For example, the from parameter in SEC filings tools conflicts with Python's from keyword.

Status: Version 2.6.9 addressed this by renaming from to from_date in affected schemas.

Source: Issue #93 Source: CHANGELOG.md

Batch Quote Endpoint False Positive

The getBatchQuotesShort tool may incorrectly return "ACCESS DENIED" errors for Ultimate plan users. This is a false positive in the MCP layer's plan-gate logic that blocks the request before it reaches the FMP API.

Status: This issue is tracked in Issue #100.

Source: Issue #100

Registry Integration

The server is listed on multiple MCP registries for discovery:

Source: README.md

Version History

Source: CHANGELOG.md

See Also

• Configuration Guide — Detailed configuration options and environment setup
• Usage Guide — Client-specific setup and session management
• API Reference — Complete tool catalog with parameters
• AGENTS.md — Non-obvious pitfalls, invariants, and anti-patterns
• Contributing Guide — Development setup and contribution guidelines

Related Pages

Related topics: Configuration Guide, Troubleshooting

Installation Guide

This guide covers all supported methods for installing and deploying the Financial Modeling Prep MCP Server. The server provides 250+ financial data tools via the Model Context Protocol (MCP), enabling AI assistants to access real-time stock quotes, financial statements, SEC filings, and other market data through the Financial Modeling Prep API.

Prerequisites

Before installing the MCP server, ensure your environment meets the following requirements:

Source: package.json:engines

Verifying Node.js Version

node --version
npm --version

If you need to upgrade Node.js, consider using nvm or downloading directly from nodejs.org.

Installation Methods

The FMP MCP Server supports multiple installation approaches depending on your use case and infrastructure preferences.

Hosted Instance (No Installation)

The fastest way to get started without any local installation:

https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp

Provide your FMP_ACCESS_TOKEN in session configuration and connect directly. This method requires no installation but relies on an external service.

Source: README.md#Quick-Start

NPX (Zero Install)

Use npx to run the server without global installation:

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

This approach downloads the package temporarily and runs it. Suitable for quick testing or one-off usage.

Source: README.md#Self-Hosted

NPM Global Installation

For persistent local installations:

npm install -g financial-modeling-prep-mcp-server

After installation, verify the binary is available:

fmp-mcp --help

Run the server with your API token:

fmp-mcp --fmp-token=YOUR_FMP_API_KEY

Source: package.json#bin

Docker Installation

For containerized deployments, build and run the server using Docker:

#### Building the Image

docker build -t fmp-mcp-server .

The Dockerfile uses a multi-stage build to compile TypeScript and create a minimal production image.

Source: Dockerfile

#### Running the Container

docker run -d \
  --name fmp-mcp \
  -p 3000:3000 \
  -e FMP_ACCESS_TOKEN=YOUR_FMP_API_KEY \
  fmp-mcp-server

#### Docker Compose Example

version: '3.8'

services:
  fmp-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - FMP_ACCESS_TOKEN=${FMP_ACCESS_TOKEN}
    restart: unless-stopped

MCP Registry Installation

The server is listed on multiple MCP registries for easy discovery and integration with MCP clients:

Source: README.md#Registries

Configuration

Command-Line Arguments

The server accepts the following CLI arguments:

Example:

fmp-mcp --fmp-token=YOUR_KEY --port=8080 --dynamic-tool-discovery

Source: server.json#arguments

Environment Variables

Source: server.json#environmentVariables

Server Modes

The FMP MCP Server operates in three modes:

graph TD
    A[FMP MCP Server Startup] --> B{Mode Selection}
    B -->|Dynamic| C[Load Meta-Tools + All Tool Definitions]
    B -->|Static| D[Load Selected Tool Sets at Startup]
    B -->|All Tools| E[Load All 253+ Tools]
    
    C --> F[Runtime Tool Discovery Available]
    D --> G[Meta-Tools Disabled]
    E --> H[Full Tool Suite]

• Dynamic Mode: Provides 5 meta-tools to load/unload tool sets at runtime
• Static Mode: Pre-loads specific tool sets defined at startup
• All Tools Mode: Loads the complete tool suite (default)

Source: README.md#Features

Token Configuration

Obtaining an FMP API Key

1. Sign up at financialmodelingprep.com
2. Navigate to your dashboard
3. Copy your API key

Token Precedence

The server uses the following precedence order for API token resolution:

1. Context/Session Token: Provided during MCP session initialization
2. Instance Configuration: Command-line --fmp-token argument
3. Environment Variable: FMP_ACCESS_TOKEN in the environment

Source: CLAUDE.md#Key-Invariants

Common Configuration Issues

#### Issue: "Missing FMP_API_TOKEN"

Users have reported difficulty setting the FMP API key through certain MCP clients, particularly when using Smithery.ai or similar registry-based connections. This manifests as connection failures or "Missing FMP_API_TOKEN" errors.

Resolution Steps:

1. Verify the environment variable is set: echo $FMP_ACCESS_TOKEN
2. If using Docker, pass the variable: -e FMP_ACCESS_TOKEN=your_key
3. If using command line, use the explicit flag: --fmp-token=your_key
4. For Smithery.ai integration, ensure the OAuth fields are properly configured in Settings > Apps

Source: GitHub Issue #81

Verification

After installation, verify the server is functioning correctly:

Health Check Endpoint

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy"
}

CLI Help Verification

fmp-mcp --help

Expected output should display all available command-line options including --fmp-token, --port, and --dynamic-tool-discovery.

Source: scripts/verify-installation-methods.ts#HELP_PATTERNS

Required Files Verification

The installation should include these core files:

Source: scripts/verify-installation-methods.ts#REQUIRED_FILES

Build from Source

For development or custom deployments, build the server from source:

Clone and Setup

git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server.git
cd Financial-Modeling-Prep-MCP-Server
npm install

Build

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Source: package.json#scripts

Development Mode

For active development with hot-reload:

npm run dev

Production Start

npm start

Integration with AI Clients

Claude Desktop

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "financial-modeling-prep": {
      "command": "fmp-mcp",
      "args": ["--fmp-token", "YOUR_API_KEY"]
    }
  }
}

Custom MCP Clients

Connect using the HTTP/SSE endpoint:

http://localhost:3000/mcp

Configure your MCP client to use this URL with session headers for authentication.

Source: docs/USAGE.md

Troubleshooting

Installation Fails with Permission Error

If you encounter EACCES errors during global npm installation:

sudo npm install -g financial-modeling-prep-mcp-server

Or configure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Server Starts but Returns 401

A 401 Unauthorized response typically means:

1. The FMP API key is invalid or expired
2. The token is not being passed correctly to the server
3. Your FMP subscription has expired

Verify your token is valid by checking the FMP dashboard.

Docker Container Exits Immediately

Check container logs:

docker logs fmp-mcp

Common causes include missing FMP_ACCESS_TOKEN environment variable or port conflicts.

MCP Client Cannot Connect

Ensure the server is listening on the correct interface:

fmp-mcp --port=3000

Verify the endpoint is accessible:

curl http://localhost:3000/health

See Also

• Configuration Reference — Detailed configuration options
• Usage Guide — Client integration and session management
• API Reference — Complete tool catalog
• Architecture Overview — System design and components
• Troubleshooting Guide — Common issues and solutions

Related Pages

Related topics: Installation Guide, Quick Start Guide, Troubleshooting

Configuration Guide

This guide covers all configuration options for the Financial Modeling Prep MCP Server, including environment variables, CLI arguments, server modes, tool set management, and session-level configuration. Understanding these options is essential for proper deployment and operation.

Overview

The FMP MCP Server provides flexible configuration through multiple mechanisms:

• Environment Variables: Persistent configuration for containerized or production deployments
• CLI Arguments: Quick configuration for command-line usage
• Session Configuration: Per-request authentication via MCP session headers

Configuration follows a clear precedence hierarchy, and the server enforces validation at startup to prevent runtime errors. Source: docs/CONFIGURATION.md

Configuration Precedence

The server resolves configuration values using a strict precedence order. Higher-precedence sources override lower-precedence ones:

graph TD
    A["1. Session Config<br/>(MCP Request Headers)"] --> B["2. CLI Arguments"]
    A --> B
    B --> C["3. Environment Variables"]
    B --> C
    C --> D["4. Defaults"]
    
    style A fill:#90EE90
    style B fill:#FFE4B5
    style C fill:#ADD8E6
    style D fill:#D3D3D3

Token Precedence (for authentication):

1. FMP_ACCESS_TOKEN from session configuration headers
2. --fmp-token CLI argument
3. FMP_ACCESS_TOKEN environment variable

Source: CLAUDE.md - Key Invariants

Environment Variables

Environment variables provide the most common configuration method for self-hosted deployments.

Core Configuration

Tool Set Configuration

Security

Source: server.json

Setting Environment Variables

Linux/macOS:

export FMP_ACCESS_TOKEN="your_fmp_api_key"
export FMP_TOOL_SETS="quotes,statements,news"
export PORT=3000

Docker:

docker run -e FMP_ACCESS_TOKEN="your_fmp_api_key" \
           -e FMP_TOOL_SETS="quotes,statements" \
           -p 3000:3000 \
           imbentabi/financial-modeling-prep-mcp-server

Docker Compose:

services:
  fmp-mcp:
    image: imbentabi/financial-modeling-prep-mcp-server
    environment:
      - FMP_ACCESS_TOKEN=${FMP_ACCESS_TOKEN}
      - FMP_TOOL_SETS=quotes,statements,news
      - PORT=3000
    ports:
      - "3000:3000"

CLI Arguments

The server accepts CLI arguments for quick configuration:

npx financial-modeling-prep-mcp-server [options]

Available Options

Examples

# Basic usage with token
npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

# Custom port
npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY --port=8080

# Specific tool sets
npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY --fmp-tool-sets=quotes,statements

# Dynamic discovery mode
npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY --dynamic-tool-discovery

Source: server.json

Session Configuration

Session configuration allows per-request authentication through MCP session headers. This is the highest-precedence configuration source.

Supported Session Parameters

Important Limitations

Note: Only FMP_ACCESS_TOKEN takes effect at the session level. The following parameters exist in the schema but are not honored per-session:

- FMP_TOOL_SETS

- DYNAMIC_TOOL_DISCOVERY

The server mode is fixed at startup and cannot be changed during runtime. Source: CHANGELOG.md - v2.6.7

Setting Session Headers

When connecting to the hosted instance or making direct MCP requests:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "headers": {
      "FMP_ACCESS_TOKEN": "your_fmp_api_key"
    }
  }
}

Smithery.ai Integration

When using Smithery.ai to configure the MCP server, ensure you set the FMP_ACCESS_TOKEN in the App configuration under Settings > Apps. The token must be provided even if OAuth fields are left blank.

Troubleshooting: If you encounter "ACCESS DENIED" errors despite having a valid token, verify that the token is properly set in the session configuration. See Issue #81 for common pitfalls.

Server Modes

The server operates in one of three modes, determined at startup:

graph TD
    A[Server Start] --> B{Mode Configuration}
    B -->|Dynamic| C["Dynamic Mode<br/>(Meta-tools enabled)<br/>250+ tools + 5 meta-tools"]
    B -->|Static| D["Static Mode<br/>(Pre-loaded toolsets)<br/>Selected tools only"]
    B -->|All| E["All Tools Mode<br/>(Default)<br/>250+ tools"]
    
    style C fill:#90EE90
    style D fill:#FFE4B5
    style E fill:#ADD8E6

Mode Comparison

Dynamic Mode (Meta-Tools)

When --dynamic-tool-discovery is enabled, the server exposes meta-tools for runtime tool management:

Source: src/toolception-adapters/ToolCollector.ts

Tool Sets

Tool sets group related tools for selective loading. The server includes 24 predefined tool sets covering different financial data categories.

Available Tool Sets

Loading Specific Tool Sets

# Via CLI
npx financial-modeling-prep-mcp-server \
  --fmp-token=YOUR_FMP_API_KEY \
  --fmp-tool-sets=quotes,statements,news

# Via environment variable
export FMP_TOOL_SETS="quotes,statements,news"

Loading Multiple Tool Sets

# Comma-separated list
--fmp-tool-sets=quotes,statements,indexes,crypto

# All tools (default)
--fmp-tool-sets=all

Source: src/constants/toolSets.ts

Validation and Startup

The server performs strict validation at startup to ensure configuration correctness.

Validation Rules

graph LR
    A[Startup] --> B{Token Valid?}
    B -->|No| C[Warning - API calls will fail]
    B -->|Yes| D{Tool Sets Valid?}
    D -->|Invalid| E[process.exit(1)]
    D -->|Valid| F{Mode Enforced?}
    F -->|Yes| G[Server Ready]
    E --> H[Error logged]
    
    style C fill:#FFE4B5
    style E fill:#FFB6C1
    style G fill:#90EE90

Key Invariants

1. API Key as Query Parameter: FMP requires the API key as a query parameter (?apikey=), never as a header
2. Token Precedence: Context > Instance > Environment
3. Fail-Fast Validation: Invalid tool sets cause process.exit(1) at startup
4. Session Restrictions: Only FMP_ACCESS_TOKEN takes effect at session level
5. Read-Only Tools: All tools are read-only data fetchers
6. Error Handling: Tools never throw; return { isError: true }

Source: CLAUDE.md - Key Invariants

Startup Warnings

The server logs warnings when configuration may cause issues:

[FMP MCP Server] No server-level FMP access token configured.
Provide via: (1) FMP_ACCESS_TOKEN env var, (2) --fmp-token CLI arg,
or (3) session config {"FMP_ACCESS_TOKEN":"your_token"}.
Without auth, API calls will fail.

Source: src/index.ts

Authentication Configuration

Obtaining an FMP API Token

1. Sign up at Financial Modeling Prep
2. Navigate to your dashboard
3. Copy your API key from the API section

Token Configuration Examples

Hosted Instance (Smithery.ai, Claude.ai, etc.): Set FMP_ACCESS_TOKEN in your client's session configuration.

Self-Hosted (npm):

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_API_KEY

Self-Hosted (Docker):

docker run -e FMP_ACCESS_TOKEN=YOUR_API_KEY \
           -p 3000:3000 \
           imbentabi/financial-modeling-prep-mcp-server

Environment File (.env):

FMP_ACCESS_TOKEN=YOUR_API_KEY
PORT=3000
FMP_TOOL_SETS=quotes,statements

Authentication Flow

sequenceDiagram
    participant Client
    participant MCP_Server
    participant FMP_API
    
    Client->>MCP_Server: MCP Request + FMP_ACCESS_TOKEN
    MCP_Server->>MCP_Server: Validate token presence
    MCP_Server->>FMP_API: API Request + apikey query param
    FMP_API->>MCP_Server: Financial Data
    MCP_Server->>Client: MCP Response

Known Configuration Issues

Issue: FMP API KEY Impossible to Set

Symptom: "ACCESS DENIED" error claiming missing FMP_API_TOKEN

Common Causes:

1. Token not provided in session configuration
2. Using wrong token variable name (FMP_API_TOKEN instead of FMP_ACCESS_TOKEN)
3. Smithery.ai app not configured with the token

Solution:

# Verify token is set
echo $FMP_ACCESS_TOKEN

# Set explicitly
export FMP_ACCESS_TOKEN="your_actual_token"

# For Smithery, ensure Settings > Apps has the token configured

Source: Issue #81

Issue: Batch Quote Endpoint False Positive

Symptom: Ultimate plan users get "ACCESS DENIED" for batch-quote endpoint

Cause: The MCP layer performs plan-gating before the request reaches FMP API. This is a known false positive in the plan validation logic.

Status: Reported in Issue #100

Issue: Python Reserved Keywords in Parameters

Symptom: Python MCP clients fail to parse tool schemas

Cause: Some tool parameters used reserved Python keywords (e.g., from, class) or invalid identifiers

Resolution: In v2.6.9, the from parameter was renamed to from_date to avoid Python conflicts.

Source: Issue #93, CHANGELOG.md v2.6.9

Production Deployment

Recommended Production Configuration

# docker-compose.yml
services:
  fmp-mcp:
    image: imbentabi/financial-modeling-prep-mcp-server:latest
    environment:
      - FMP_ACCESS_TOKEN=${FMP_ACCESS_TOKEN}
      - FMP_TOOL_SETS=all
      - PORT=3000
      - NODE_ENV=production
      - ALLOWED_ORIGINS=https://your-app.com
      - RATE_LIMIT_MAX=100
      - RATE_LIMIT_WINDOW=60000
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Health Check Endpoint

The server exposes a health check endpoint:

GET http://localhost:3000/health

Response:

{
  "status": "healthy",
  "version": "2.6.10",
  "timestamp": "2026-04-30T00:00:00.000Z"
}

Readiness Check

GET http://localhost:3000/ready

Returns 200 OK when the server is ready to accept requests.

Configuration Reference

Complete Environment Variables

# Required
FMP_ACCESS_TOKEN=your_fmp_api_key

# Server
PORT=3000
NODE_ENV=production

# Tool Sets
FMP_TOOL_SETS=all  # or: quotes,statements,news,crypto
DYNAMIC_TOOL_DISCOVERY=false

# Security
ALLOWED_ORIGINS=https://your-domain.com
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=60000

# Logging
LOG_LEVEL=info

Complete CLI Options

fmp-mcp [options]

Options:
  -t, --fmp-token <token>        FMP API access token
  -p, --port <port>              Server port (default: 3000)
  --fmp-tool-sets <sets>         Comma-separated tool sets
  --dynamic-tool-discovery       Enable dynamic tool discovery
  --allowed-origins <origins>   CORS allowed origins
  -h, --help                     Show help

See Also

• Usage Guide — Client-specific setup and session management
• API Reference — Complete tool catalog
• Architecture Overview — Server architecture and components
• Contributing Guide — Development setup

Related Pages

Related topics: Installation Guide, Configuration Guide, Usage Guide

Quick Start Guide

This guide provides a rapid path to getting the Financial Modeling Prep MCP Server operational. It covers installation methods, authentication configuration, server modes, and resolution of common setup issues.

Overview

The Financial Modeling Prep MCP Server is a Model Context Protocol (MCP) server that exposes 250+ financial data tools to AI assistants. It acts as a bridge between AI clients (such as Claude Desktop) and the Financial Modeling Prep API, enabling real-time access to stock quotes, financial statements, SEC filings, market data, and more.

Key capabilities:

• 250+ financial data tools across 24 categories
• Three server modes: Dynamic (meta-tools for on-demand loading), Static (pre-loaded toolsets), and All Tools
• HTTP/SSE transport for compatibility with Claude.ai, Claude Desktop, and MCP registries
• Token-based authentication with flexible configuration options

Source: README.md

Prerequisites

Before beginning, ensure your environment meets the following requirements:

Source: package.json:34-36

Installation Methods

The server can be deployed using several methods, ranging from zero-configuration hosted access to full self-hosting.

Hosted Instance (Fastest)

The hosted instance requires no installation. Connect directly using the provided endpoint:

https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp

Provide your FMP_ACCESS_TOKEN in your session configuration to authenticate.

Source: README.md:19-23

NPM Installation (Self-Hosted)

Install globally via npm for local execution:

npm install -g financial-modeling-prep-mcp-server

Run with your API token:

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

Or using the CLI binary directly:

fmp-mcp --fmp-token=YOUR_FMP_API_KEY

Source: README.md:26-32

NPX (No Installation Required)

Execute directly without installing:

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

Source: README.md:26

Authentication Configuration

Authentication is performed using the Financial Modeling Prep API key. The server supports multiple configuration methods with a defined precedence order.

Token Precedence (Highest to Lowest)

Source: CLAUDE.md:17

Configuration via Environment Variable

Set the API token as an environment variable before starting the server:

export FMP_ACCESS_TOKEN="your_fmp_api_key"
fmp-mcp

Configuration via CLI Flag

Pass the token directly to the server binary:

fmp-mcp --fmp-token=your_fmp_api_key

Configuration via Session (Dynamic Mode)

In Dynamic mode, the server accepts session-level configuration. Pass FMP_ACCESS_TOKEN when initiating an MCP session:

{
  "FMP_ACCESS_TOKEN": "your_fmp_api_key"
}

Important: Only FMP_ACCESS_TOKEN takes effect at the session level. The schema also accepts FMP_TOOL_SETS and DYNAMIC_TOOL_DISCOVERY, but these are no-ops at session time—server mode is fixed at startup from environment and CLI arguments.

Source: src/toolception-adapters/AGENTS.md:8-10

Common Authentication Issues

Issue: "Missing FMP_API_TOKEN" error

This commonly occurs when deploying via MCP registries like Smithery.ai. Users report difficulties setting the API key through registry interfaces.

Resolution:

1. Ensure FMP_ACCESS_TOKEN is set as an environment variable in your deployment environment
2. When using Smithery or similar registries, verify the OAuth fields are properly configured or left blank if not required
3. Check that your MCP client is passing the token in session configuration

Source: GitHub Issue #81

Server Modes

The server operates in three distinct modes, determined by configuration at startup.

Mode Comparison

Source: README.md:14-16

Enabling Dynamic Mode

Dynamic mode provides meta-tools for runtime toolset management. Enable via:

CLI flag:

fmp-mcp --dynamic-tool-discovery

Environment variable:

export DYNAMIC_TOOL_DISCOVERY=true
fmp-mcp

Source: server.json:24-30

Loading Specific Tool Sets (Static Mode)

Specify which toolsets to load at startup using the --fmp-tool-sets option:

fmp-mcp --fmp-tool-sets=quotes,statements,sec-filings

Available tool sets include: quotes, statements, sec-filings, search, directory, company, metrics, technicals, indexes, market, news, insider, etfs, government, crypto, earnings, special, commodities, economics, and bulk.

Source: CLAUDE.md:11

Available Tools

The server exposes financial tools across 24 categories. Below are the primary tool sets:

Source: README.md:43-48

MCP Client Configuration

Different MCP clients have varying configuration requirements. Below are common setup patterns.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "financial-modeling-prep": {
      "command": "npx",
      "args": ["financial-modeling-prep-mcp-server", "--fmp-token", "YOUR_FMP_API_KEY"]
    }
  }
}

Source: docs/USAGE.md

Session Header Configuration

When using Dynamic mode with the hosted instance, pass authentication via session headers:

{
  "FMP_ACCESS_TOKEN": "your_api_key"
}

Architecture Overview

The following diagram illustrates the server's layered architecture:

graph TD
    A[MCP Client<br/>Claude, etc.] --> B[MCP Protocol Layer<br/>toolception]
    B --> C[Tools Layer<br/>28 modules, 250+ tools]
    C --> D[API Layer<br/>FMPClient + Domain Clients]
    D --> E[Financial Modeling Prep API]
    
    F[CLI/Env Config] -->|Mode & Token| B
    G[Session Config] -->|Token Only| B

Key architectural characteristics:

• Toolception framework: Enables dynamic tool registration and runtime management
• Never-throw pattern: Tools return { isError: true } instead of throwing exceptions
• API key as query parameter: FMP requires ?apikey= on requests, never headers

Source: CLAUDE.md:1-10 Source: src/tools/AGENTS.md:4-6

Tool Usage Example

Fetching a Stock Quote

// Tool name: getQuote
// Parameters: symbol (required)
{
  "symbol": "AAPL"
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"symbol\": \"AAPL\",\n  \"name\": \"Apple Inc.\",\n  \"price\": 178.50,\n  \"change\": 2.35,\n  \"changePercent\": 1.33\n}"
    }
  ]
}

Batch Quotes

Fetch multiple quotes in a single request:

// Tool name: getBatchQuotesShort
// Parameters: symbols (comma-separated)
{
  "symbols": "AAPL,GOOGL,MSFT"
}

Note: If you receive an "ACCESS DENIED" error claiming your plan is insufficient when using batch quotes with an Ultimate plan subscription, this may indicate a false positive in the MCP layer's plan-gate logic. This issue is being tracked in GitHub Issue #100.

Known Limitations and Workarounds

Python Reserved Keywords (v2.6.9+)

Some tools previously used parameter names that conflict with Python reserved keywords, causing issues for Python-based MCP clients.

Affected patterns (fixed in v2.6.9):

• from → renamed to from_date (Python reserved keyword)
• Other reserved keywords and invalid identifiers

Workaround for older versions: Quote parameters explicitly when calling tools that may have reserved keyword conflicts.

Source: CHANGELOG.md:12-15 Source: GitHub Issue #93

Batch Quote Plan-Gate False Positive

The batch-quote endpoint may incorrectly block requests from Ultimate plan users with an "ACCESS DENIED" error. This is a false positive in the MCP layer's plan-gate logic that occurs before the request reaches the FMP API.

Status: Issue #100 is open and being tracked.

Port Configuration

The server defaults to port 3000 but can be configured:

Example:

fmp-mcp --fmp-token=YOUR_KEY --port=8080

Source: server.json:16-22

Registry Integration

The server is listed on multiple MCP registries for discovery:

Source: README.md:55-61

Troubleshooting Checklist

If you encounter issues, verify the following:

• [ ] Node.js version ≥ 25.3.0
• [ ] npm version ≥ 11.11.0
• [ ] Valid FMP API key with appropriate subscription tier
• [ ] FMP_ACCESS_TOKEN environment variable set (or passed via CLI/session)
• [ ] Port 3000 available (or custom port configured)
• [ ] Server started successfully with fmp-mcp --fmp-token=YOUR_KEY

Verifying Installation

Test your installation:

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_KEY

The server should start and listen on the configured port.

Health Check

The server provides health and readiness endpoints:

• GET /health - Basic health check
• GET /ready - Readiness probe

Next Steps

• Explore tools: See docs/API_REFERENCE.md for the complete tool catalog
• Detailed usage: Review docs/USAGE.md for client-specific configuration
• Development: See CONTRIBUTING.md for development setup
• Architecture deep-dive: See AGENTS.md for architectural invariants

See Also

• README.md - Project overview and features
• docs/USAGE.md - Detailed usage documentation
• docs/API_REFERENCE.md - Complete tool catalog
• AGENTS.md - Architectural invariants and pitfalls
• CHANGELOG.md - Version history and release notes

Related Pages

Related topics: API Reference, Quick Start Guide, Troubleshooting

Usage Guide

This guide covers how to install, configure, and use the Financial Modeling Prep MCP Server. It explains the different server modes, tool sets, authentication mechanisms, and integration patterns for various MCP clients.

Overview

The Financial Modeling Prep MCP Server is a Model Context Protocol server that exposes 250+ financial data tools via the FMP API. The server supports multiple deployment methods and provides flexible configuration options for different use cases.

Key characteristics:

• HTTP/SSE transport (no stdio support)
• Three server modes: Dynamic, Static, and All Tools
• Token-based authentication with environment, CLI, and session-level configuration
• Built on the toolception framework for runtime tool management
• Source: README.md:1-30

graph TD
    A[MCP Client] -->|HTTP/SSE| B[FMP MCP Server]
    B -->|Token Validation| C{Token Source}
    C -->|Environment| D[Environment Variable]
    C -->|CLI| E[Command Line Flag]
    C -->|Session| F[Request Context]
    B -->|API Calls| G[FMP API]
    G -->|Financial Data| B

Installation Methods

The server can be installed and run through several methods depending on your environment and requirements.

NPM Installation (Global)

Install globally for command-line usage across your system:

npm install -g financial-modeling-prep-mcp-server

After installation, run the server with your API token:

fmp-mcp --fmp-token=YOUR_FMP_API_KEY

Source: package.json:7-20

NPX (No Installation)

Run directly without installation using NPX:

npx financial-modeling-prep-mcp-server --fmp-token=YOUR_FMP_API_KEY

This method is useful for testing or temporary usage without modifying your system.

Docker Deployment

For containerized environments, build and run the Docker image:

FROM node:25-alpine
RUN npm install -g financial-modeling-prep-mcp-server
EXPOSE 3000
CMD ["fmp-mcp", "--port=3000", "--fmp-token=${FMP_API_TOKEN}"]

Source: docs/USAGE.md:1-50

Hosted Instance

Use the hosted server without any installation:

https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp

This requires providing your FMP_ACCESS_TOKEN in session configuration.

Configuration

Environment Variables

Source: server.json:15-45

Command Line Arguments

Token Configuration Precedence

The server uses the following precedence order for token resolution (highest to lowest):

1. Session Context — Token provided in the MCP session configuration
2. CLI Arguments — --fmp-token flag at startup
3. Environment Variables — FMP_ACCESS_TOKEN environment variable

Important: The FMP API requires the token as a query parameter (?apikey=), never as an HTTP header. This is handled automatically by the server's API clients.

Source: src/api/AGENTS.md:1-20

Server Modes

The MCP server operates in three modes, determined by environment variables and CLI flags at startup.

Mode Comparison

Dynamic Tool Discovery Mode

When DYNAMIC_TOOL_DISCOVERY=true is set, the server provides five meta-tools for runtime tool management:

graph LR
    A[Session Start] --> B[Load 5 Meta-Tools]
    B --> C[getAvailableToolSets]
    B --> D[loadToolSet]
    B --> E[unloadToolSet]
    B --> F[getLoadedToolSets]
    B --> G[searchTools]
    
    C --> H[List All Available Tool Sets]
    D --> I[Load Selected Tool Set]
    E --> J[Remove Tool Set from Session]

Meta-tools available:

• getAvailableToolSets — List all available tool sets
• getLoadedToolSets — List currently loaded tool sets
• loadToolSet — Load a specific tool set by name
• unloadToolSet — Unload a specific tool set
• searchTools — Search tools across all sets

Note: Only FMP_ACCESS_TOKEN can be configured per-session. Other parameters like FMP_TOOL_SETS and DYNAMIC_TOOL_DISCOVERY are fixed at startup and cannot be changed during a session.

Source: src/toolception-adapters/AGENTS.md:1-25

Static Tool Sets Mode

Load specific tool sets by comma-separating their names:

FMP_TOOL_SETS=quotes,statements,fcas npx financial-modeling-prep-mcp-server

Tool Sets and Categories

The server organizes its 250+ tools into 24 tool sets. Each tool set corresponds to a functional domain of financial data.

Available Tool Sets

Source: src/constants/toolSets.ts

Using Tools

Tools are called via the MCP protocol using the tool name and parameters. Example for getting a stock quote:

{
  "name": "getQuote",
  "arguments": {
    "symbol": "AAPL"
  }
}

Batch quotes example:

{
  "name": "getBatchQuotesShort",
  "arguments": {
    "symbols": "AAPL,MSFT,GOOGL"
  }
}

Source: src/tools/quotes.ts:40-75

MCP Client Integration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "financial-modeling-prep": {
      "url": "https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp",
      "headers": {
        "FMP_ACCESS_TOKEN": "your_api_key_here"
      }
    }
  }
}

Smithery.ai

The server is registered on Smithery.ai. Configuration varies by client, but typically requires:

1. Server URL: https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp
2. OAuth fields: Leave blank (the server uses token-based auth)
3. Headers: Provide FMP_ACCESS_TOKEN in session configuration

Source: docs/REGISTRIES.md:1-60

Python MCP Clients

Known Issue: Some tool schemas use parameter names that conflict with Python reserved keywords or contain invalid identifiers. This can break Python-based MCP clients.

Workaround: Version 2.6.9+ renamed the from parameter to from_date in affected tools to avoid Python reserved keyword conflicts.

See: Issue #93

HTTP Endpoints

The server exposes HTTP endpoints for health checking and readiness verification.

Source: src/endpoints/index.ts:1-80

Health check response:

{
  "status": "ok",
  "timestamp": "2026-04-30T12:00:00.000Z"
}

Readiness check response:

{
  "status": "ready",
  "toolsLoaded": 253,
  "version": "2.6.10"
}

Common Issues and Troubleshooting

Issue: "ACCESS DENIED" for Ultimate Plan Users

Known Bug: The batch-quote endpoint may incorrectly return ACCESS DENIED for Ultimate plan users. This is a false positive in the MCP layer's plan-gating logic that occurs before the request reaches the FMP API.

See: Issue #100

Workaround: Use individual getQuote calls instead of getBatchQuotesShort until this is fixed.

Issue: FMP API Key Configuration

Users have reported difficulty setting the API key, especially when using Smithery.ai integration.

See: Issue #81

Resolution steps:

1. Ensure FMP_ACCESS_TOKEN is set as an environment variable or CLI flag
2. For Smithery, provide the token in session headers, not OAuth fields
3. Verify the token is valid at financialmodelingprep.com

Issue: Session Not Found Errors

In dynamic mode, "Session not found" errors typically indicate:

• The clientId changed between requests
• The sessionConfigHash differs from the original session

Ensure consistent session parameters:

{
  "clientId": "consistent-client-id",
  "sessionConfig": {
    "FMP_ACCESS_TOKEN": "your_token"
  }
}

Source: src/toolception-adapters/AGENTS.md:20-25

Error Handling

Tools follow a consistent error handling pattern:

1. Never throw exceptions — Tools return error responses with isError: true
2. Error format — Error messages follow the pattern Error: ${message}
3. Response structure:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid symbol provided"
    }
  ],
  "isError": true
}

Source: src/tools/AGENTS.md:1-20

See Also

• Configuration Reference — Detailed configuration options
• API Reference — Complete tool catalog
• Architecture Overview — System architecture and components
• Registry Setup — MCP registry integration guides
• Contributing Guide — Development setup and PR guidelines

Related Pages

Related topics: Usage Guide, Tool Development Guide

API Reference

Overview

The Financial Modeling Prep MCP Server exposes 250+ financial data tools via the Model Context Protocol (MCP), providing AI assistants with access to the Financial Modeling Prep (FMP) API. The API layer serves as the foundational bridge between the MCP protocol layer and the external FMP financial data service.

Source: README.md

Architecture

The MCP server follows a layered architecture with three distinct levels:

graph TD
    A["MCP Protocol Layer<br/>(toolception + Fastify)"] --> B["Tools Layer<br/>(28 modules, 253+ tools)"]
    B --> C["API Layer<br/>(FMPClient + 28 domain clients)"]
    C --> D["Financial Modeling Prep API"]

API Client Structure

The API layer consists of an abstract base client and 28 domain-specific clients, each responsible for a particular category of financial data. Source: src/api/index.ts

Key Invariant: API Key as Query Parameter

FMP requires the API key to be passed as a query parameter, never as an HTTP header. This is a critical constraint enforced throughout the codebase.

FMP requires ?apikey=, never headers

Source: src/api/AGENTS.md

Tool Categories

The server organizes 253+ tools into 24 logical categories. Each category maps to one or more API clients and exposes multiple related tools.

Source: docs/API_REFERENCE.md

Complete Tool Category Reference

Source: README.md

Tool Registration Pattern

All MCP tools follow a consistent registration pattern defined in src/tools/. Each tool module exports a registration function that binds domain-specific handlers to the MCP server instance.

Source: src/tools/index.ts

Registration Function Signature

export function registerQuotesTools(
  server: McpServer,
  accessToken?: string
): void

Each registration function:

1. Creates a domain-specific API client instance
2. Registers each tool with server.tool()
3. Wraps API calls in error handling that returns { isError: true } instead of throwing

Source: src/tools/quotes.ts:6-16

Required Tool Rules

Tools must adhere to strict rules to maintain protocol compatibility:

Source: src/tools/AGENTS.md

Quotes Tools Reference

The Quotes category provides access to real-time and historical stock quote data.

Source: src/tools/quotes.ts

getQuote

Get real-time stock quote data for a single symbol.

server.tool(
  "getQuote",
  "Access real-time stock quotes with the FMP Stock Quote API.",
  {
    symbol: z.string().describe("Stock symbol"),
  },
  async ({ symbol }) => {
    const results = await quotesClient.getQuote({ symbol });
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

getBatchQuotesShort

Get short-form quotes for multiple stocks in a single request.

Note: There is a known issue where batch-quote endpoints may be incorrectly blocked for Ultimate plan users due to a false positive in the MCP layer plan-gate logic. See Issue #100.

getBatchAftermarketTrade

Retrieve aftermarket trading data for multiple symbols.

Financial Statements Tools Reference

Access company financial statements including income statements, balance sheets, and cash flow statements.

Source: src/tools/statements.ts

getIncomeStatement

server.tool(
  "getIncomeStatement",
  "Access real-time income statement data for public companies.",
  {
    symbol: z.string().describe("Stock symbol"),
    limit: z.number().optional().describe("Limit on number of results"),
    period: z.enum(["Q1", "Q2", "Q3", "Q4", "FY"]).optional().describe("Period"),
  },
  async ({ symbol, limit, period }) => {
    const results = await statementsClient.getIncomeStatement(symbol, { limit, period });
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

SEC Filings Tools Reference

Access SEC filing documents including 8-K, 10-K, and 10-Q reports.

Source: src/tools/sec-filings.ts

getLatest8KFilings

Important: The parameter from_date was renamed from from in v2.6.9 to avoid Python reserved keyword conflicts. See Issue #93 and CHANGELOG.md.

Earnings Tools Reference

Access earnings data including transcripts, calendar, and estimates.

Source: src/tools/earnings-transcript.ts

getLatestEarningsTranscripts

Toolception Integration

The server uses toolception to enable dynamic tool management, supporting three server modes:

Source: src/toolception-adapters/ToolCollector.ts

Server Modes

Source: README.md

ToolCollector Architecture

The ToolCollector class serves as a virtual MCP server that intercepts tool registrations from existing registerXxxTools() functions and converts them to toolception's McpToolDefinition format.

classDiagram
    class ToolCollector {
        +tools: McpToolDefinition[]
        +tool(name, description, schema, handler): void
        +getTools(): McpToolDefinition[]
    }
    
    class McpToolDefinition {
        +name: string
        +description: string
        +inputSchema: Record
        +handler: Function
        +annotations: object
    }

Source: src/toolception-adapters/ToolCollector.ts:1-50

Configuration Reference

Command-Line Arguments

Source: server.json

Environment Variables

*Required for API access. May be provided via CLI arg --fmp-token or session configuration.

Token Precedence

The system enforces the following precedence for API token resolution:

1. Context — Token provided in session configuration
2. Instance — Token provided via CLI argument
3. Environment — Token provided via FMP_ACCESS_TOKEN environment variable

Source: src/api/AGENTS.md

Known Limitations and Issues

Issue #100: Batch-Quote False Positive Blocking

The batch-quote endpoint may incorrectly return ACCESS DENIED errors for Ultimate plan users. This occurs at the MCP layer before the request reaches the FMP API, representing a false positive in the plan-gate logic.

Status: Open issue requiring investigation of MCP layer access control.

Source: Issue #100

Issue #93: Python Reserved Keywords in Parameter Names

Several tools use parameter names that conflict with Python reserved keywords or contain invalid identifiers, breaking Python-based MCP clients.

Resolved in v2.6.9: The from parameter was renamed to from_date in relevant tools (e.g., SEC filings).

Status: Ongoing effort to identify and rename all problematic parameter names.

Source: Issue #93, CHANGELOG.md

Issue #81: FMP API Key Configuration

Users have reported difficulty setting the FMP API key, particularly when using registry integrations like Smithery.ai.

Recommended Solutions:

1. Set FMP_ACCESS_TOKEN environment variable directly
2. Use --fmp-token CLI argument for self-hosted deployments
3. Provide via session configuration when supported by the MCP client

Source: Issue #81

Error Handling

All tools follow a consistent error handling pattern that prevents exceptions from propagating to the MCP protocol layer:

try {
  const results = await quotesClient.getQuote({ symbol });
  return {
    content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
  };
} catch (error) {
  return {
    content: [
      {
        type: "text",
        text: `Error: ${
          error instanceof Error ? error.message : String(error)
        }`,
      },
    ],
    isError: true,
  };
}

This ensures that MCP clients receive well-formed responses regardless of API failures.

Source: src/tools/quotes.ts:22-35

API Version Compatibility

The server targets specific versions of Node.js and npm:

Source: package.json

See Also

• README.md — Project overview and quick start
• docs/USAGE.md — Client-specific setup instructions
• docs/REGISTRIES.md — MCP registry integration guides
• AGENTS.md — Agent-focused invariants and anti-patterns
• CONTRIBUTING.md — Development setup and contribution guidelines

Related Pages

Related topics: Overview, Tool Development Guide

System Architecture

Overview

The Financial Modeling Prep MCP Server is a Model Context Protocol (MCP) server implementation that exposes 250+ financial data tools to AI assistants through the Financial Modeling Prep (FMP) API. Built on Node.js with the toolception framework, it provides a middleware layer that translates MCP tool invocations into FMP API calls.

Purpose: Enable AI assistants like Claude to access real-time and historical financial data including stock quotes, financial statements, SEC filings, market indexes, cryptocurrency data, and more.

Scope: The server operates as a read-only data proxy—it fetches data from FMP's API endpoints and returns structured JSON responses. It does not perform any write operations, market analysis, or calculations.

Source: CLAUDE.md

Related Pages

Related topics: System Architecture, Contributing Guide

Tool Development Guide

This guide provides comprehensive instructions for extending the Financial Modeling Prep MCP Server with new tools, modules, and tool sets. It covers the complete development workflow, from adding a single tool to creating entirely new functional modules.

Overview

The FMP MCP Server exposes 250+ financial data tools organized into 24 categories. These tools bridge the gap between the Model Context Protocol (MCP) and the Financial Modeling Prep API. The tool development framework follows a layered architecture where each new capability flows through four distinct layers: API client → tool registration → toolception adapter → tool set mapping.

Purpose: Enable contributors to add new financial data tools without understanding the full MCP protocol internals.

Scope: Adding individual tools, creating new modules, and defining tool sets for dynamic discovery.

Source: GUIDE.md

Architecture

Tool Registration Flow

The following diagram illustrates how a new tool moves from development through to runtime availability:

graph TD
    A[Create API Client Method] --> B[Register Tool in Module]
    B --> C[Create Toolception Adapter]
    C --> D[Map to Tool Set]
    D --> E[Dynamic Discovery Available]
    
    F[MCP Client Request] --> G[toolception Framework]
    G --> H[Tool Handler Execution]
    H --> I[API Client Method]
    I --> J[FMP API]
    
    style A fill:#e1f5fe
    style E fill:#c8e6c9
    style J fill:#fff3e0

Layer Responsibilities

Source: GUIDE.md

Adding a New Tool

When extending existing functionality within a module, follow this three-step process:

Step 1: Add Method to API Client

API clients live in src/api/{domain}/. Each domain has its own client class. Add a method that handles the HTTP request to FMP:

// src/api/quotes/QuotesClient.ts
async getBatchQuotes(params: BatchQuotesParams): Promise<Quote[]> {
  const queryParams = new URLSearchParams({
    apikey: this.accessToken,
    ...params,
  });
  
  const response = await fetch(
    `${FMP_BASE_URL}/v3/quotes?${queryParams}`
  );
  
  if (!response.ok) {
    throw new Error(`FMP API error: ${response.status}`);
  }
  
  return response.json();
}

Source: src/tools/quotes.ts:38-54

Step 2: Register Tool in Module

Add the tool registration to the corresponding module file under src/tools/. Use the server.tool() method with a Zod schema:

import { z } from "zod";
import { QuotesClient } from "../api/quotes/QuotesClient.js";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerQuotesTools(
  server: McpServer,
  accessToken?: string
): void {
  const quotesClient = new QuotesClient(accessToken);

  server.tool(
    "getBatchQuotes",
    "Retrieve batch stock quotes for multiple symbols in a single request.",
    {
      symbols: z.string().describe("Comma-separated list of stock symbols"),
    },
    async ({ symbols }) => {
      try {
        const results = await quotesClient.getBatchQuotes({ symbols });
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );
}

Source: src/tools/quotes.ts:1-47

Step 3: Verify Zod Schema Pattern

Ensure your parameter schema follows these conventions:

⚠️ Known Issue: Issue #93 reported that Python reserved keywords in parameter names break Python MCP clients. The project addressed this by renaming from to from_date in version 2.6.9.

Source: src/tools/sec-filings.ts:20-29

Creating a New Module

A complete module consists of four components that must be created together:

Module Creation Checklist

Source: GUIDE.md

Step 1: Create the API Client

Create a new directory under src/api/ with your domain name and implement a client class:

// src/api/example/ExampleClient.ts
export class ExampleClient {
  private accessToken: string;
  private baseUrl = "https://financialmodelingprep.com/api/v4";

  constructor(accessToken?: string) {
    this.accessToken = accessToken || process.env.FMP_ACCESS_TOKEN || "";
  }

  async getExampleData(params: ExampleParams): Promise<ExampleResult[]> {
    // Implementation
  }
}

Step 2: Create Tool Registration Module

Create the corresponding tool registration file:

// src/tools/example.ts
import { z } from "zod";
import { ExampleClient } from "../api/example/ExampleClient.js";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerExampleTools(
  server: McpServer,
  accessToken?: string
): void {
  const exampleClient = new ExampleClient(accessToken);

  server.tool(
    "getExample",
    "Description of what this tool does.",
    {
      param: z.string().describe("Parameter description"),
    },
    async ({ param }) => {
      try {
        const results = await exampleClient.getExampleData({ param });
        return {
          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${
                error instanceof Error ? error.message : String(error)
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );
}

Source: src/tools/statements.ts

Step 3: Create Toolception Adapter

The toolception framework enables dynamic tool discovery. Create an adapter that wraps your registration function:

// src/toolception-adapters/moduleAdapters.ts
import { createModuleAdapter } from "./createModuleAdapter.js";
import { registerExampleTools } from "../tools/example.js";

export const exampleAdapter = createModuleAdapter(
  "example",
  "Example Module Description",
  registerExampleTools
);

Source: src/toolception-adapters/ToolCollector.ts

Step 4: Map to Tool Set

Add your module to the tool sets configuration:

// src/constants/toolSets.ts
export const TOOL_SETS = {
  // ... existing sets
  example: {
    description: "Example financial data tools",
    modules: ["example"],
  },
} as const;

Source: GUIDE.md

Toolception Integration

The server uses the toolception framework to enable dynamic tool loading. This allows meta-tools that can enable/disable toolsets at runtime.

How Toolception Works

graph LR
    A[MCP Client] -->|list_tools| B[toolception]
    B --> C[Available Tool Definitions]
    A -->|call_tool| D[Tool Handler]
    D --> E[API Client]
    E --> F[FMP API]
    
    G[Dynamic Request] -->|enable_toolset| B
    B -->|loads| H[New Tools Available]

ToolCollector Pattern

The ToolCollector class mocks the MCP server to capture tool registrations during initialization:

// src/toolception-adapters/ToolCollector.ts
export class ToolCollector implements ToolRegistrar {
  private tools: McpToolDefinition[] = [];

  tool(
    name: string,
    description: string,
    schema: Record<string, any>,
    handler: (params: any) => Promise<any>
  ): void {
    this.tools.push({
      name,
      description,
      inputSchema: schema,
      handler,
    });
  }
}

Source: src/toolception-adapters/ToolCollector.ts:30-45

Critical Rules and Anti-patterns

Key Rules

The following rules are enforced by the tools layer and must be followed:

Source: src/tools/AGENTS.md

Anti-patterns to Avoid

// ❌ WRONG: Throwing from tool handler
async handler({ symbol }) {
  throw new Error("Invalid symbol"); // Breaks MCP protocol
}

// ✅ CORRECT: Return error response
async handler({ symbol }) {
  return {
    content: [{ type: "text", text: "Error: Invalid symbol" }],
    isError: true,
  };
}

// ❌ WRONG: Missing Error: prefix
return {
  content: [{ type: "text", text: "Something went wrong" }],
  isError: true,
};

// ✅ CORRECT: Error: prefix required
return {
  content: [{ type: "text", text: "Error: Something went wrong" }],
  isError: true,
};

Source: src/tools/AGENTS.md

Tool Annotations

All tools receive identical annotations for MCP compatibility:

Common Issues and Troubleshooting

Issue: Python Reserved Keywords

Community Issue #93: Parameter names like from and to broke Python MCP clients.

Symptoms: Python-based MCP clients fail to parse tool schemas.

Resolution: Always use from_date and to_date instead of from and to:

// src/tools/sec-filings.ts
async ({ from_date: from, to, page, limit }) => {
  // Note: Destructured as 'from_date' but passed as 'from' to API
  const results = await secFilingsClient.getLatest8KFilings({
    from,  // Variable is 'from' after destructuring
    to,
    page,
    limit,
  });
}

Source: src/tools/sec-filings.ts:20-36

Issue: Duplicate Tool Names

Symptom: Later registration silently overwrites earlier tools with the same name.

Prevention: Check existing tool names in all module files before adding new tools.

Issue: API Token Configuration

Community Issue #81: Users struggled to set the FMP API token.

Resolution: The token can be configured via:

• FMP_ACCESS_TOKEN environment variable
• --fmp-token command-line argument
• Session configuration (for hosted instances)

Testing New Tools

Manual Testing

# Start the server in development mode
npm run dev

# Test with a MCP inspector or client
npx @modelcontextprotocol/inspector

Automated Testing

Add tests to the appropriate test directory following the existing patterns in __tests__/.

See Also

• Architecture Overview - High-level system design
• Configuration Guide - Server configuration options
• Usage Guide - Client integration patterns
• API Reference - Complete tool catalog
• Contributing Guide - Development setup

Related Pages

Related topics: Tool Development Guide, System Architecture

Contributing Guide

This guide covers how to contribute to the Financial Modeling Prep MCP Server project. It addresses development environment setup, code architecture patterns, testing requirements, and the release process.

Prerequisites

Before contributing, ensure your development environment meets the following requirements:

Source: package.json

Repository Structure

Understanding the codebase structure is essential before making contributions. The project follows a layered architecture:

graph TD
    A[MCP Protocol Layer<br/>toolception framework] --> B[Tools Layer<br/>28 modules, 253+ tools]
    B --> C[API Layer<br/>FMPClient + 28 domain clients]
    C --> D[Financial Modeling Prep API]

    subgraph src/
        E[api/] --> F[HTTP clients for FMP API]
        G[tools/] --> H[MCP tool registrations]
        I[toolception-adapters/] --> J[Framework integration]
        K[server-mode-enforcer/] --> L[Mode configuration]
        M[constants/] --> N[Tool sets and defaults]
        O[endpoints/] --> P[HTTP endpoints]
        Q[prompts/] --> R[MCP prompt definitions]
    end

Source: CLAUDE.md

Directory Reference

Source: CONTRIBUTING.md

Development Setup

Initializing the Environment

1. Clone the repository:

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

1. Install dependencies:

npm install

1. Build the project:

npm run build

Available npm Scripts

The project provides comprehensive npm scripts for development and quality assurance:

Source: package.json

Development Workflow

graph LR
    A[Edit Code] --> B[npm run dev]
    B --> C[TypeScript compiles<br/>with watch mode]
    C --> D[Run Tests]
    D --> E{Tests Pass?}
    E -->|No| A
    E -->|Yes| F[npm run lint]
    F --> G{Lint Clean?}
    G -->|No| A
    G -->|Yes| H[Submit Pull Request]

Architecture Rules and Anti-Patterns

Key Invariants

The codebase enforces several critical rules that contributors must understand:

1. API Key as Query Parameter — The FMP API requires the API key as a query parameter (?apikey=), never as HTTP headers.
2. Token Precedence — Context > Instance > Environment variable hierarchy.
3. Fail-Fast Validation — Invalid tool sets cause process.exit(1) at startup.
4. Read-Only Tools — All tools are read-only data fetchers.
5. Error Handling — Tools never throw; they return { isError: true } with an error message.

Source: CLAUDE.md

Tool Layer Rules

When working in src/tools/, follow these rules:

Source: src/tools/AGENTS.md

Anti-Patterns to Avoid

• Never throw from tool handlers — The MCP protocol expects errors in the response, not exceptions
• Never use duplicate tool names — Later registration silently overwrites earlier ones

Source: src/tools/AGENTS.md

Adding New Tools

Adding a Tool to an Existing Module

For extending existing functionality:

1. Add the API method to the appropriate client in src/api/{domain}/
2. Register the tool in src/tools/{module}.ts
3. Follow the Zod schema pattern for parameters

Example tool registration pattern:

server.tool(
  "getQuote",
  "Access real-time stock quotes with the FMP Stock Quote API.",
  {
    symbol: z.string().describe("Stock symbol"),
  },
  async ({ symbol }) => {
    try {
      const results = await quotesClient.getQuote({ symbol });
      return {
        content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }
);

Source: src/tools/quotes.ts

Adding a New Module

When creating an entirely new domain:

1. Create src/api/{domain}/{Domain}Client.ts — HTTP client for FMP API
2. Create src/tools/{module}.ts — Tool registration function
3. Add adapter in src/toolception-adapters/moduleAdapters.ts — Framework integration
4. Map to tool set in src/constants/toolSets.ts — Tool set definition

Adding a New Tool Set

1. Add definition to TOOL_SETS in src/constants/toolSets.ts
2. Add type to ToolSet union in src/types/index.ts

Source: GUIDE.md

Testing Requirements

Test Suite Structure

Source: AGENTS.md

Running Tests

# Run tests in watch mode during development
npm run test

# Run tests once (CI/CD)
npm run test:run

# Run with coverage report
npm run test:coverage

Smoke Test Requirements

Smoke tests have specific requirements that must be met:

• Build first — Run npm run build before executing smoke tests
• SSE parsing — Verify Server-Sent Events are properly parsed
• Global session state — Tests must handle singleton state correctly

Source: AGENTS.md - __tests__/smoke/AGENTS.md

Code Quality Standards

TypeScript

The project uses strict TypeScript typing throughout. Before committing:

# Check types without emitting
npm run typecheck

Linting

The project uses oxlint with warnings treated as errors:

# Check for linting issues
npm run lint

# Auto-fix issues
npm run lint:fix

Dependency Management

Use knip to identify unused dependencies and exports:

# Find unused code
npm run knip

# Remove unused code
npm run knip:fix

Version Management

Version Synchronization

The project uses a version synchronization script to keep version numbers consistent across files:

# Validate version consistency
npm run version:validate

# Sync versions across all files
npm run version:sync

# Display version information
npm run version:info

The script maintains version consistency in:

• package.json
• package-lock.json
• README.md
• CHANGELOG.md

Source: docs/version-sync.md

Versioning Policy

The project follows Semantic Versioning:

Source: CHANGELOG.md

Release Process

Release Checklist

Before creating a release:

1. Update version in package.json
2. Run version synchronization: npm run version:sync
3. Update CHANGELOG.md with new version section
4. Verify GitHub secrets are configured: npm run verify:github-secrets
5. Create git tag: git tag v{version}
6. Push changes and tag: git push origin main --tags

Automated Publishing

Starting with version 2.5.0, releases are fully automated through GitHub Actions:

Source: CHANGELOG.md

Publishing Workflow

graph TD
    A[git tag v{version}] --> B[Push to origin]
    B --> C[GitHub Actions Triggered]
    C --> D{NPM_TOKEN valid?}
    D -->|Yes| E[Publish to NPM Registry]
    D -->|No| F[Fail with clear error]
    E --> G[Update MCP Registry]
    G --> H[Create GitHub Release]
    H --> I[Release Notes Generated]

Manual Publishing

For manual deployment, use the scripts/manual-publish.ts script:

npx tsx scripts/manual-publish.ts [options]

Options include --dry-run, --skip-npm, --skip-registry, --skip-validation, and --force.

Pull Request Guidelines

Before Submitting

1. Run all checks locally:

npm run build && npm run test:run && npm run lint && npm run typecheck

1. Update documentation if adding features or changing behavior

1. Update CHANGELOG.md under the [Unreleased] section

1. Follow the directory structure — place related code in appropriate directories

Commit Messages

Use clear, descriptive commit messages that explain what changed and why.

Handling Known Issues

Be aware of known issues that may affect contributions:

Source: Community Issues #93, #100

Navigation to Related Documentation

See Also

• README.md — Project overview and quick start
• AGENTS.md — Non-obvious pitfalls and invariants
• CHANGELOG.md — Version history and release notes
• docs/USAGE.md — Client-specific setup instructions

Related Pages

Related topics: Configuration Guide, Installation Guide, Usage Guide

Troubleshooting

This page provides guidance for diagnosing and resolving common issues with the Financial Modeling Prep MCP Server. It covers configuration problems, error patterns, and debugging techniques based on the server's architecture and known issues.

Overview

The FMP MCP Server exposes 250+ financial data tools via the Model Context Protocol, acting as a bridge between AI assistants and the Financial Modeling Prep API. Troubleshooting typically involves three layers:

1. Configuration Layer — API token setup, environment variables, and session configuration
2. MCP Protocol Layer — Tool registration, schema validation, and plan-gate enforcement
3. API Layer — HTTP client communication with FMP endpoints

Understanding which layer an error originates from is essential for effective troubleshooting.

Common Issues

API Token Configuration

The most frequently reported issue involves setting the FMP API token correctly. The server supports three configuration methods with a specific precedence order.

#### Token Precedence

Session Config > Instance Config > Environment Variable

Source: docs/USAGE.md

#### Configuration Methods

#### Resolving "Missing FMP_ACCESS_TOKEN" Errors

If you encounter errors indicating the token is missing, verify the following:

1. For Smithery.ai deployments: The token must be set in session configuration, not OAuth fields. Create your app with blank OAuth fields and provide FMP_ACCESS_TOKEN through the session config interface.

``bash FMP_ACCESS_TOKEN=your_token npx financial-modeling-prep-mcp-server ``

1. For self-hosted deployments: Ensure the token is available at startup:

`` [FMP MCP Server] No server-level FMP access token configured. ``

1. Check server logs: The server logs a warning if no token is configured:

Source: src/index.ts

#### Session Configuration Schema

Only FMP_ACCESS_TOKEN is effective at the session level. Other parameters like FMP_TOOL_SETS and DYNAMIC_TOOL_DISCOVERY exist in the schema but are no-ops—mode configuration is fixed at server startup.

interface SessionConfig {
  FMP_ACCESS_TOKEN: string;
}

Source: src/schemas/SessionConfigSchema.ts

Plan-Gate False Positives

#### Issue: Batch Quote Endpoint Blocked for Ultimate Plan Users

A known issue (#100) causes the getBatchQuotesShort tool to return "ACCESS DENIED" errors for users on the Ultimate plan. The block occurs at the MCP layer before the request reaches the FMP API.

Symptom:

Error: ACCESS DENIED - This endpoint is available on higher-tier plans

Root Cause: The MCP layer's plan-gate validation incorrectly identifies batch quote endpoints as requiring a premium tier even when the user's FMP plan includes access.

Workaround: Use individual quote requests instead of batch requests:

• Instead of getBatchQuotesShort, use multiple getQuote calls
• Individual quote requests bypass the faulty plan-gate validation

Status: This is a known bug tracked in issue #100.

Python Reserved Keywords in Parameter Names

#### Issue: Tool Schemas Incompatible with Python MCP Clients

Issue #93 identifies that several tools use parameter names that conflict with Python reserved keywords or contain invalid identifiers.

Two Categories of Problems:

1. Python Reserved Keywords: Parameters named from, list, type, id, str, int, float, bool, lambda, class, def, return, import, export, async, await, try, except, finally, with, as, pass, break, continue, raise, yield, global, nonlocal, assert, del, in, is, not, or, and, None, True, False.

1. Invalid Identifiers: Parameters starting with numbers or containing special characters.

Resolution (v2.6.9+): Starting with version 2.6.9, the from parameter was renamed to from_date in affected tools. Check the CHANGELOG.md for the complete list of renamed parameters.

Example Fix:

// Before (v2.6.8)
async ({ from, to, page, limit }) => { ... }

// After (v2.6.9+)
async ({ from_date: from, to, page, limit }) => { ... }

Source: src/tools/sec-filings.ts

Error Handling Patterns

Tool Layer Error Contract

All MCP tools follow a strict error handling contract defined in src/tools/AGENTS.md:

Source: src/tools/AGENTS.md

Standard Error Response Format

{
  content: [{
    type: "text",
    text: "Error: descriptive error message"
  }],
  isError: true
}

Common Error Messages

Debugging Techniques

Enabling Verbose Logging

The server outputs detailed configuration information at startup. Review the logs for:

[FMP MCP Server] Toolception config: {
  "startup": "...",
  "exposurePolicy": "...",
  "catalogKeys": [...],
  "moduleLoaderKeys": [...]
}

Source: src/index.ts

Client ID Header Injection

The server includes middleware that injects an mcp-client-id header when missing. This addresses compatibility issues with MCP clients that don't send the required header:

// If mcp-client-id is missing, a stable client ID is generated
// based on request fingerprint (IP, user-agent, etc.)

Source: src/index.ts

Key Invariants for Diagnostics

These invariants, defined in CLAUDE.md, help identify where issues occur:

Version-Specific Issues

Version 2.6.9 — Python Keyword Fix

This release renamed from to from_date to avoid Python reserved keyword conflicts. If you're using older tooling that relies on the old parameter name, update to match the new schema.

Version 2.6.7 — Session Config Clarification

Documentation was clarified to explicitly state that only FMP_ACCESS_TOKEN can be set per-session. Previous confusion arose from other parameters appearing in the schema.

Getting Help

If you encounter an issue not covered here:

1. Check the Issues to see if it's a known bug
2. Search the CHANGELOG.md for recent fixes
3. Enable verbose logging to capture detailed error information
4. Report new issues with:

• Server version (npm list financial-modeling-prep-mcp-server)
• Complete error message
• Steps to reproduce
• MCP client and configuration details

See Also

• README.md — Project overview and quick start
• docs/USAGE.md — Detailed usage instructions
• docs/API_REFERENCE.md — Complete tool catalog
• src/tools/AGENTS.md — Tool layer implementation guidelines

Doramagic Pitfall Log

Doramagic extracted 10 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients

• Severity: medium
• Finding: Installation risk is backed by a source signal: Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/93

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | no_demo; severity=medium

5. Security or permission risk: No sandbox install has been executed yet; downstream must verify before user use.

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.safety_notes | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | No sandbox install has been executed yet; downstream must verify before user use.

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | no_demo; severity=medium

7. Security or permission risk: FMP API KEY impossible to set

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: FMP API KEY impossible to set. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/81

8. Security or permission risk: batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/100

9. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | issue_or_pr_quality=unknown

10. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using financial-modeling-prep-mcp-server with real data or production workflows.

• batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP p - github / github_issue
• Tool input schemas use Python reserved keywords and invalid identifiers - github / github_issue
• FMP API KEY impossible to set - github / github_issue
• Release v2.6.9 - github / github_release
• Release v2.6.5 - github / github_release
• Release v2.6.4 - github / github_release
• Release v2.6.3 - github / github_release
• README/documentation is current enough for a first validation pass. - GitHub / issue