项目简介

Financial-Modeling-Prep-MCP-Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 助手提供访问 Financial Modeling Prep (FMP) 金融数据 API 的能力。该项目通过 MCP 协议将 FMP 的丰富金融数据（包括股票报价、财务报表、新闻、SEC 文件等）封装为一组可被 AI 客户端调用的工具。资料来源：README.md

该项目采用 TypeScript 开发，支持动态工具发现和静态工具集两种运行模式，可通过 npm 全局安装或通过 MCP 注册表进行集成。最新版本为 v2.6.10，已发布至 NPM Registry 和 MCP Registry。资料来源：package.json

核心架构

系统组件

graph TD
    A[MCP 客户端] --> B[MCP 服务器]
    B --> C[工具发现层]
    C --> D[工具集目录]
    D --> E[模块加载器]
    E --> F[API 客户端]
    F --> G[FMP API]
    
    H[会话配置] --> B
    I[环境变量] --> B
    J[命令行参数] --> B

技术栈

资料来源：package.json:测试依赖

服务器运行模式

该项目支持三种服务器运行模式，通过 ServerMode 类型定义：

资料来源：src/types/index.ts:ServerMode

配置映射机制

ModeConfigMapper 类负责将 FMP 的服务器模式转换为 toolception 框架的配置格式：

graph LR
    A[ServerMode] --> B[ModeConfigMapper]
    B --> C[ToolceptionConfig]
    C --> D[startup.mode]
    C --> E[catalog]
    C --> F[moduleLoaders]

工具集分类

项目将功能划分为 24 个工具集，涵盖金融数据的各个领域：

资料来源：src/types/index.ts:ToolSet

工具集定义结构

每个工具集在 src/constants/toolSets.ts 中定义为 ToolSetDefinition：

interface ToolSetDefinition {
  name: string;           // 工具集显示名称
  description: string;    // 功能描述
  decisionCriteria: string; // 决策帮助文本
  modules: string[];      // 关联的模块列表
}

项目目录结构

资料来源：CONTRIBUTING.md:项目结构

配置方式

环境变量配置

命令行参数

资料来源：server.json:Arguments

已知问题与限制

社区反馈的问题

根据社区 issue 反馈，以下问题需要关注：

资料来源：GitHub Issues

版本兼容性要求

• Node.js: >= 25.3.0
• npm: >= 11.11.0

低于上述版本的运行环境可能导致兼容性问题。

安装与部署

NPM 全局安装

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

MCP 注册表安装

该项目已注册至多个 MCP 注册表：

• Smithery.ai
• Glama.ai
• MCP Registry

Docker 部署

从源码构建 Docker 镜像：

docker build -t fmp-mcp-server .
docker run -e FMP_ACCESS_TOKEN=<your-token> fmp-mcp-server

版本历史

资料来源：CHANGELOG.md

许可证

项目采用 Apache-2.0 许可证开源。资料来源：LICENSE

系统要求

资料来源：package.json:engine-requirements

安装方式

NPM 全局安装（推荐）

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

安装完成后，通过以下命令验证：

npx financial-modeling-prep-mcp-server --help

NPX 方式运行

无需预安装，直接使用：

npx financial-modeling-prep-mcp-server

MCP 注册表安装

该服务器已在多个 MCP 注册表上线，支持一键安装：

资料来源：README.md:registries

配置 API 密钥

服务器需要有效的 FMP API 密钥才能正常运作。有两种配置方式：

环境变量方式

export FMP_ACCESS_TOKEN="your_api_key_here"

运行时参数方式

financial-modeling-prep-mcp-server --fmp-token "your_api_key_here"

注意：根据用户反馈（issue #81），部分用户在使用 Smithery.ai 部署时遇到 API 密钥配置问题。确保环境变量名称为 FMP_ACCESS_TOKEN，而非 FMP_API_TOKEN。

资料来源：server.json:arguments

工具集配置

服务器支持按需加载功能模块，通过工具集（Tool Sets）进行管理：

资料来源：src/constants/toolSets.ts:modules

配置工具集参数

financial-modeling-prep-mcp-server --fmp-tool-sets "quotes,news,statements"

或通过环境变量：

export FMP_TOOL_SETS="quotes,news,statements"

服务器模式

资料来源：src/types/index.ts:ServerMode

快速验证

创建测试文件 test-tools.js：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { quotesTools } from "./dist/tools/quotes.js";
import { newsTools } from "./dist/tools/news.js";

const server = new McpServer({
  name: "fmp-test",
  version: "1.0.0"
});

quotesTools(server);
newsTools(server);

const transport = new StdioServerTransport();
server.connect(transport);

运行测试：

node test-tools.js

开发环境设置

如需参与开发，完整设置流程如下：

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

开发期间使用监视模式：

npm run dev

资料来源：CONTRIBUTING.md:setup

提交前检查清单

常见问题

Python 客户端兼容性问题

在 v2.6.9 中，参数名称已从 from 改为 from_date，以避免 Python 保留关键字冲突。如果使用 Python MCP 客户端框架，请确保更新到最新版本。

batch-quote 端点权限问题

部分 Ultimate 计划用户报告了 batch-quote 端点的误报权限错误。这是由 MCP 层而非 FMP API 本身触发的假阳性。

版本验证

确保版本一致性：

npm run version:validate

资料来源：CHANGELOG.md:v2.6.9

下一步

• 阅读完整文档：docs/USAGE.md
• 查看 API 参考：docs/API_REFERENCE.md
• 配置说明：docs/CONFIGURATION.md

架构概述

该服务器采用分层架构设计，核心目标是将复杂的金融数据 API 封装为 MCP 协议兼容的工具集，使 AI 代理能够通过标准化的工具调用访问财务数据。

graph TB
    subgraph "客户端层"
        A["AI 助手 / MCP 客户端"]
    end
    
    subgraph "MCP 协议层"
        B["MCP SDK 服务器"]
        C["JSON-RPC 处理器"]
    end
    
    subgraph "业务逻辑层"
        D["工具注册层"]
        E["API 客户端层"]
        F["服务器模式执行器"]
    end
    
    subgraph "外部服务层"
        G["FMP API"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> G
    
    F --> D
    F --> E
    
    style G fill:#ffcccc

核心目录结构

项目源代码位于 src/ 目录下，按职责划分为多个子模块：

资料来源：CONTRIBUTING.md

服务器模式体系

服务器支持三种运行模式，通过 ServerMode 类型定义：

type ServerMode = 'DYNAMIC_TOOL_DISCOVERY' | 'STATIC_TOOL_SETS' | 'ALL_TOOLS';

资料来源：src/types/index.ts:31

模式详细说明

工具集（Tool Sets）

系统将相关工具组织为工具集，支持按需加载：

type ToolSet =
  | "search"           // 股票搜索
  | "company"          // 公司信息
  | "quotes"           // 报价数据
  | "statements"       // 财务报表
  | "calendar"         // 财务日历
  | "charts"           // 价格图表
  | "news"             // 金融新闻
  | "analyst"          // 分析师覆盖
  | "market-performance"  // 市场表现
  | "insider-trades"   // 内部人交易
  | "institutional"    // 机构持仓
  | "indexes"          // 指数数据
  | "economics"        // 经济数据
  | "crypto"           // 加密货币
  | "forex"            // 外汇
  | "commodities"      // 大宗商品
  | "etf-funds"        // ETF基金
  | "esg"              // ESG评级
  | "technical-indicators"  // 技术指标
  | "senate"           // 政府交易
  | "sec-filings"      // SEC文件
  | "earnings"         // 财报与电话会议
  | "dcf"              // DCF估值
  | "bulk";            // 批量数据工具

资料来源：src/types/index.ts:18-29

每个工具集包含以下元数据：

interface ToolSetDefinition {
  name: string;           // 可读名称
  description: string;    // 功能描述
  decisionCriteria: string;  // 用户选择此工具集的条件
  modules: string[];      // 关联的内部模块列表
}

资料来源：src/types/index.ts:34-39

API 客户端架构

FMPClient 核心客户端

FMPClient 是与 Financial Modeling Prep API 通信的核心客户端，负责处理 HTTP 请求、认证和响应解析：

graph LR
    A["工具调用"] --> B["Zod Schema 验证"]
    B --> C["API 客户端方法"]
    C --> D["HTTP 请求构建"]
    D --> E["FMP API 响应"]
    E --> F["类型安全的数据返回"]

领域特定客户端

API 客户端按功能域划分为多个子模块，目录结构为 src/api/{domain}/：

• insider-trades/ - 内部人交易数据
• 新闻、股票报价、财务报表等...

每个领域客户端返回强类型的响应对象，确保数据处理的类型安全：

// 示例：内部人交易响应类型
interface InsiderTradeResponse {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDisposablePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}

资料来源：src/api/insider-trades/types.ts:1-18

工具注册系统

工具定义模式

每个 MCP 工具通过 @modelcontextprotocol/sdk 注册，遵循标准化模式：

server.tool(
  "toolName",                    // 工具标识符
  "工具描述...",                  // 功能说明
  {
    // Zod Schema 定义的参数
    param1: z.string().describe("参数描述"),
    param2: z.number().optional().describe("可选参数")
  },
  async ({ param1, param2 }) => {
    // 工具实现逻辑
    const result = await apiClient.method({ param1, param2 });
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
    };
  }
);

资料来源：src/tools/news.ts:1-30

参数命名规范

已知问题：某些工具曾使用 Python 保留字作为参数名（如 from），这会导致 Python MCP 客户端解析失败。在 v2.6.9 版本中已修复，将 from 重命名为 from_date：

v2.6.9 更新说明：

- 重命名 from 参数为 from_date 以避免 Python 保留字冲突

- 更新 @modelcontextprotocol/sdk 依赖至 ^1.27.1

资料来源：CHANGELOG.md

配置系统

上下文类型

服务器通过 FMPContext 传递运行时配置：

export type FMPContext = {
  config?: {
    FMP_ACCESS_TOKEN?: string;
  };
};

资料来源：src/types/index.ts:5-9

会话配置

会话级别的配置支持动态调整：

interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;      // API 访问令牌
  FMP_TOOL_SETS?: string;         // 工具集列表
  DYNAMIC_TOOL_DISCOVERY?: string; // 动态发现开关
}

资料来源：src/types/index.ts:44-49

配置来源优先级

graph TD
    A["命令行参数"] --> B["环境变量"]
    B --> C["会话配置"]
    C --> D["服务器默认值"]
    
    style A fill:#90EE90
    style D fill:#FFB6C1

命令行参数定义

资料来源：server.json

环境变量

资料来源：server.json

模式配置映射器

ModeConfigMapper 是连接服务器模式与工具集的核心组件：

graph TB
    A["ModeConfigMapper"] --> B["resolveServerMode"]
    A --> C["resolveToolSets"]
    A --> D["buildToolCatalog"]
    
    B --> E["DYNAMIC_TOOL_DISCOVERY<br/>STATIC_TOOL_SETS<br/>ALL_TOOLS"]
    C --> F["工具集列表"]
    D --> G["工具目录"]

主要职责包括：

1. 解析服务器模式 - 根据执行器配置确定运行模式
2. 解析工具集 - 从执行器获取要加载的工具集列表
3. 构建工具目录 - 生成工具集的完整元数据目录

资料来源：src/toolception-adapters/ModeConfigMapper.ts

MCP 协议集成

SDK 版本

项目依赖 @modelcontextprotocol/sdk 进行 MCP 协议实现，当前版本要求：

{
  "@modelcontextprotocol/sdk": "^1.27.1"
}

传输层

服务器支持标准 MCP 传输机制，通过 stdio 进行本地通信，或通过 HTTP 服务器模式提供网络访问。

扩展指南

添加新工具

1. 在 src/api/{domain}/ 中添加 API 客户端方法
2. 在 src/tools/{module}.ts 中注册 MCP 工具
3. 使用 Zod schema 定义参数

添加新工具集

1. 在 TOOL_SETS 中添加定义（src/constants/toolSets.ts）
2. 在 ToolSet 联合类型中添加新类型（src/types/index.ts）

添加新模块

1. 创建 src/api/{domain}/{Domain}Client.ts
2. 创建 src/tools/{module}.ts 注册函数
3. 在 src/toolception-adapters/moduleAdapters.ts 中添加适配器
4. 在 src/constants/toolSets.ts 中映射到工具集

已知问题与限制

计划门控误报

Issue #100 报告：batch-quote 端点对 Ultimate 计划用户错误返回 ACCESS DENIED。该问题发生在 MCP 层而非 API 层，属于计划检查的误报。

Python 客户端兼容性

Issue #93 报告：工具参数名曾使用 Python 保留字（如 from、to），已通过 v2.6.9 版本将 from 重命名为 from_date 修复。

API 密钥配置

Issue #81 报告：部分部署方式下 FMP_API_TOKEN 配置困难。建议通过环境变量 FMP_ACCESS_TOKEN 或命令行参数 --fmp-token 设置。

运行时要求

资料来源：CONTRIBUTING.md, package.json

技术栈

概述

API 客户端层是 Financial Modeling Prep MCP Server 与外部 FMP API 之间的通信桥梁。该层封装了所有 HTTP 请求逻辑，负责认证、请求构建、响应解析以及错误处理，使上层工具注册代码无需直接处理底层网络细节。资料来源：src/api/FMPClient.ts()

架构设计

客户端组织结构

客户端按照功能域进行模块化划分，每个业务领域拥有独立的客户端模块：

资料来源：src/api/FMPClient.ts()

分层架构图

graph TD
    A[MCP 工具层] --> B[API 客户端层]
    B --> C[FMPClient 核心客户端]
    C --> D[QuotesClient]
    C --> E[CompanyClient]
    C --> F[StatementsClient]
    C --> G[NewsClient]
    D --> H[FMP REST API]
    E --> H
    F --> H
    G --> H
    H --> I[FMP API 服务器]

核心组件详解

FMPClient 主客户端

FMPClient 是所有 API 客户端的基类，负责管理访问令牌和提供统一的 API 调用接口：

// 核心结构
export class FMPClient {
  constructor(accessToken: string, baseUrl?: string);
  
  // 域客户端实例
  readonly quotes: QuotesClient;
  readonly company: CompanyClient;
  readonly statements: StatementsClient;
  // ... 其他域客户端
}

客户端通过构造函数接收访问令牌，该令牌通过会话配置或环境变量获取。资料来源：src/api/FMPClient.ts()

QuotesClient 报价客户端

报价客户端负责获取各类金融产品的实时和历史报价数据：

• 股票报价：单支股票实时价格、批量报价
• 加密货币报价：实时加密货币价格
• 外汇报价：实时外汇汇率
• 指数报价：市场指数数据

资料来源：src/api/quotes/QuotesClient.ts()

CompanyClient 公司客户端

公司客户端提供公司相关信息的数据访问：

• 公司概况和基本信息
• 公司估值指标
• 符号搜索功能
• 财务比率分析

资料来源：src/api/company/CompanyClient.ts()

StatementsClient 财务报表客户端

财务报表客户端封装了 FMP API 的财务报表相关端点：

• 资产负债表 (balance-sheet-statement)
• 利润表 (income-statement)
• 现金流量表 (cash-flow-statement)
• 财务报表完整列表

资料来源：src/api/statements/StatementsClient.ts()

类型定义系统

新闻数据类型

新闻 API 返回统一格式的数据结构：

export interface NewsArticle {
  symbol: string | null;
  publishedDate: string;
  publisher: string;
  title: string;
  image: string;
  site: string;
  text: string;
  url: string;
}

export interface NewsParams {
  from?: string;
  to?: string;
  page?: number;
  limit?: number;
}

资料来源：src/api/news/types.ts()

内幕交易类型

export interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}

资料来源：src/api/insider-trades/types.ts()

类型组织结构

错误处理机制

客户端层错误处理

API 客户端采用统一的错误处理模式，通过 try-catch 捕获异常并返回结构化的错误响应：

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,
  };
}

这种模式确保所有 API 调用错误都能以一致的格式返回，便于上层工具层统一处理。资料来源：src/tools/news.ts()

社区问题：批量报价端点误报

根据社区反馈 issue #100，批量报价端点 (batch-quote) 对 Ultimate 计划用户错误返回 ACCESS DENIED 错误。该问题发生在 MCP 层而非 API 层，表明需要检查客户端层的计划验证逻辑是否正确传递用户权限状态。资料来源：Issue #100()

请求参数规范

新闻 API 参数

注意：在 v2.6.9 版本中，参数名 from 已重命名为 from_date，以避免与 Python 保留关键字冲突。资料来源：CHANGELOG.md()

13F 表单参数

与工具层的集成

工具注册模式

API 客户端通过标准模式注册为 MCP 工具：

1. 创建客户端实例，注入访问令牌
2. 在工具定义中引用客户端方法
3. 使用 Zod 进行输入参数验证
4. 统一错误处理和响应格式化

server.tool(
  "getStockNews",
  "获取最新股票市场新闻...",
  {
    from_date: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
    to: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
    page: z.number().optional().describe("页码"),
    limit: z.number().optional().describe("结果数量限制"),
  },
  async ({ from_date: from, to, page, limit }) => {
    const results = await newsClient.getStockNews({ from, to, page, limit });
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);

资料来源：src/tools/news.ts()

配置与初始化

访问令牌配置

访问令牌可通过以下方式配置：

重要：根据 v2.6.7 版本的文档更新，客户端层仅允许通过会话配置设置 FMP_ACCESS_TOKEN，其他会话配置参数不受支持。资料来源：CHANGELOG.md()

客户端实例化流程

sequenceDiagram
    participant Session as 会话配置
    participant Server as MCP 服务器
    participant FMPClient as FMPClient
    participant DomainClient as 域客户端
    
    Session->>Server: 提供 FMP_ACCESS_TOKEN
    Server->>FMPClient: 创建实例 (accessToken)
    FMPClient->>DomainClient: 创建域客户端实例
    DomainClient->>FMPClient: 返回引用
    FMPClient-->>Server: 返回完整客户端

扩展指南

添加新域客户端

1. 在 src/api/{domain}/ 目录创建 {Domain}Client.ts
2. 继承 FMPClient 或使用其方法
3. 定义相关类型接口
4. 在 FMPClient 中注册新域客户端
5. 在工具文件中注册对应 MCP 工具

命名规范

• 客户端类名：{Domain}Client (如 QuotesClient)
• 文件名：{Domain}Client.ts (如 QuotesClient.ts)
• 类型文件：src/api/{domain}/types.ts

环境要求

运行时依赖

重要提示：项目对 Node.js 版本有严格要求（>= 25.3.0），请在安装前确认当前版本。

版本验证

# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version

如版本不符合要求，请通过 Node.js 官网 或使用 nvm 进行升级。

安装方式

本服务器支持多种安装方式，可根据使用场景选择合适的方法。

NPM 全局安装

适用于需要全局访问服务器的场景：

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

安装完成后可通过以下命令验证：

npx financial-modeling-prep-mcp-server --version

NPX 临时运行

适用于一次性使用或测试场景：

npx financial-modeling-prep-mcp-server

Docker 容器化部署

对于生产环境，推荐使用 Docker 进行隔离部署。

#### 构建镜像

docker build -t financial-modeling-prep-mcp-server .

#### 运行容器

docker run -d \
  -e FMP_API_KEY=your_api_key_here \
  -p 3000:3000 \
  --name fmp-mcp-server \
  financial-modeling-prep-mcp-server

#### Dockerfile 配置说明

# 基础镜像
FROM node:25.3.0-slim

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY package*.json ./
COPY dist ./dist

# 安装依赖
RUN npm ci --only=production

# 暴露端口
EXPOSE 3000

# 启动命令
CMD ["node", "dist/index.js"]

MCP 注册表安装

服务器已注册至多个 MCP 发现平台，支持一键安装：

API 密钥配置

获取 FMP API 密钥

1. 访问 Financial Modeling Prep 官网
2. 注册账户并选择合适的订阅计划
3. 在个人设置中获取 API 密钥

环境变量配置

配置方式

#### 方式一：环境变量（推荐用于 Docker）

export FMP_API_KEY=your_api_key_here
export FMP_ACCESS_TOKEN=your_access_token_here

#### 方式二：会话配置（适用于 MCP 客户端）

某些 MCP 客户端支持在会话级别设置令牌：

{
  "mcpServers": {
    "fmp": {
      "command": "npx",
      "args": ["-y", "financial-modeling-prep-mcp-server"],
      "env": {
        "FMP_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

注意：根据社区反馈（issue #81），部分用户在 Smithery.ai 部署时遇到 API KEY 配置困难。确保使用 FMP_ACCESS_TOKEN 而非 FMP_API_KEY 进行会话级配置。资料来源：docs/CONFIGURATION.md

服务器模式

本服务器支持三种运行模式，通过 SERVER_MODE 环境变量控制：

工具集配置

使用静态工具集模式时，可通过 FMP_TOOL_SETS 指定启用的工具集：

export FMP_TOOL_SETS=quotes,company,statements

可用工具集列表

开发环境搭建

如需进行二次开发或贡献代码，请按以下步骤配置：

克隆项目

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

安装依赖

npm install

构建项目

npm run build

开发模式

使用热重载进行开发：

npm run dev

运行测试

# 运行所有测试
npm run test:run

# 监视模式运行测试
npm run test

# TypeScript 类型检查
npm run typecheck

提交前检查清单

在提交代码前，请确保完成以下验证：

npm run build
npm run test:run
npm run typecheck

部署架构

graph TD
    A[客户端应用] --> B[MCP 客户端]
    B --> C[Financial Modeling Prep MCP Server]
    C --> D{FMP API}
    D --> E[免费用户]
    D --> F[专业用户]
    D --> G[企业用户]
    D --> H[旗舰用户]
    
    I[环境配置] --> C
    I --> FMP_ACCESS_TOKEN
    I --> FMP_TOOL_SETS
    I --> SERVER_MODE

常见问题

API 密钥设置失败

问题：按照文档设置 FMP_API_TOKEN 后仍提示缺少密钥。

解决方案：

1. 确认使用的是 FMP_ACCESS_TOKEN 而非 FMP_API_KEY
2. 检查环境变量是否正确导出
3. 重启 MCP 客户端使配置生效

版本兼容性问题

问题：启动时报错 Unsupported engine。

解决方案：确保 Node.js 版本 >= 25.3.0，npm 版本 >= 11.11.0。

Docker 容器端口冲突

问题：Port 3000 is already in use

解决方案：修改映射端口：

docker run -d -p 3001:3000 --name fmp-mcp-server financial-modeling-prep-mcp-server

验证安装

安装完成后，可通过以下方式验证服务器状态：

# 检查服务是否运行
curl http://localhost:3000/health

# 或使用 MCP 客户端测试连接
mcp-cli test --server financial-modeling-prep

版本信息

完整版本历史请参阅 CHANGELOG.md。

概述

Financial Modeling Prep MCP Server 采用模块化架构设计，通过配置系统实现灵活的工具加载和访问控制。配置体系主要包含以下几个层面：

• 环境变量配置：用于设置 API 凭证和全局服务器参数
• 会话配置：支持按会话设置访问令牌和工具集范围
• 服务器模式：控制工具发现和加载的行为模式
• 工具集（Tool Sets）：将相关工具分组便于管理和授权

环境变量配置

必需配置

可选配置

注意：根据社区反馈（issue #81），部分用户在设置 FMP_API_KEY 时遇到困难。建议通过环境变量直接设置，而非依赖外部配置界面。

会话配置

会话配置允许在运行时动态调整访问权限和控制参数。配置类型定义如下：

interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;
  FMP_TOOL_SETS?: string;
  DYNAMIC_TOOL_DISCOVERY?: string;
}

会话配置限制

会话配置中仅允许设置以下参数：

⚠️ 重要：会话配置仅支持 FMP_ACCESS_TOKEN 字段的设置。其他参数（如工具集选择）必须在服务器启动时的环境变量或配置文件中指定。

服务器模式

服务器支持三种运行模式，通过 SERVER_MODE 环境变量控制：

模式类型

type ServerMode = 'DYNAMIC_TOOL_DISCOVERY' | 'STATIC_TOOL_SETS' | 'ALL_TOOLS';

模式配置映射

ModeConfigMapper 类负责解析和映射服务器模式配置：

private static resolveToolSets(enforcer: ModeEnforcerView): ToolSet[] {
  if (enforcer.serverModeOverride === 'STATIC_TOOL_SETS') {
    return enforcer.toolSets;
  }
  return [];
}

模式选择建议

graph TD
    A[选择服务器模式] --> B{使用场景}
    B -->|固定工具集<br>性能优先| C[STATIC_TOOL_SETS]
    B -->|按需加载<br>灵活性优先| D[DYNAMIC_TOOL_DISCOVERY]
    B -->|开发测试<br>全量访问| E[ALL_TOOLS]
    C --> F[需配合 FMP_TOOL_SETS 配置]
    D --> G[动态发现开销较高]
    E --> H[生产环境不推荐]

工具集（Tool Sets）

工具集是将相关功能分组的管理单元，每个工具集包含多个模块。

预定义工具集

工具集配置示例

# 启用多个工具集
FMP_TOOL_SETS=quotes,statements,news

# 或使用单一声明式配置
FMP_TOOL_SETS=quotes+statements+news

工具集结构

每个工具集定义包含以下属性：

interface ToolSetDefinition {
  name: string;              // 工具集显示名称
  description: string;       // 工具集功能描述
  decisionCriteria: string;  // 用户选择此工具集的标准
  modules: string[];         // 包含的模块列表
}

配置工作流

完整配置流程

graph TD
    A[开始配置] --> B{安装方式}
    B -->|NPM 全局安装| C[设置环境变量]
    B -->|Docker 部署| D[配置环境变量或文件]
    B -->|MCP 注册表| E[使用默认配置]
    C --> F[设置 FMP_API_KEY]
    D --> F
    E --> F
    F --> G{是否需要会话隔离}
    G -->|是| H[配置 FMP_ACCESS_TOKEN]
    G -->|否| I[选择服务器模式]
    H --> I
    I --> J{工具集需求}
    J -->|固定工具集| K[设置 STATIC_TOOL_SETS]
    J -->|按需加载| L[设置 DYNAMIC_TOOL_DISCOVERY]
    J -->|全部工具| M[设置 ALL_TOOLS]
    K --> N{配置 FMP_TOOL_SETS}
    N --> O[启动服务器]
    L --> O
    M --> O

工具参数配置

参数命名规范

⚠️ 已知问题：部分工具参数名使用了 Python 保留字（如 from），可能导致 Python MCP 客户端兼容性问题（issue #93）。

在 v2.6.9 版本中，已将 from 参数重命名为 from_date 以避免冲突：

// 工具参数定义示例
{
  from_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
  to: z.string().optional().describe("End date (YYYY-MM-DD)"),
  page: z.number().optional().describe("Page number"),
  limit: z.number().optional().describe("Result limit"),
}

常见参数类型

运行时配置验证

验证命令

# 版本一致性验证
npm run version:validate

# 类型检查
npm run typecheck

常见配置错误

安装与部署配置

NPM 安装

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

Docker 部署

# 构建镜像
docker build -t fmp-mcp-server .

# 运行容器
docker run -e FMP_API_KEY=your_api_key fmp-mcp-server

Docker 说明：从 v2.6.7 开始，Docker 安装说明已更新为从源代码构建 MCP 服务器镜像，而非使用预构建镜像。

运行时要求

配置最佳实践

开发环境

# .env.development
FMP_API_KEY=your_dev_api_key
SERVER_MODE=ALL_TOOLS
LOG_LEVEL=debug

生产环境

# 生产环境配置
FMP_API_KEY=your_prod_api_key
SERVER_MODE=STATIC_TOOL_SETS
FMP_TOOL_SETS=quotes,statements,news,analyst
LOG_LEVEL=warn

安全建议

1. 凭证管理：不要将 API Key 提交到版本控制系统
2. 会话隔离：多用户场景下使用会话级别的 FMP_ACCESS_TOKEN
3. 最小权限：仅启用所需的工具集，减少攻击面
4. 日志管理：生产环境使用 warn 或 error 日志级别

故障排除

常见问题

Q: API Key 无法设置？ A: 确保通过环境变量 FMP_API_KEY 设置，而非通过配置文件。参考 issue #81 的解决方案。

Q: 工具返回 ACCESS DENIED？ A: 确认 API Key 有效且账户订阅级别支持该功能。部分高级功能需要 Ultimate 计划订阅。

Q: Python 客户端参数错误？ A: 确保使用 v2.6.9 或更高版本，该版本已修复保留字冲突问题。

相关文档

• 使用指南 - 客户端配置和请求示例
• API 参考 - 完整工具目录
• 注册表配置 - MCP 注册表集成说明

模式概述

MCP 服务器支持三种服务器模式，每种模式对应不同的工具加载策略：

资料来源：src/types/index.ts:27-29

架构设计

服务器模式的实现采用了模块化适配器架构，核心组件包括模式配置映射器（ModeConfigMapper）、模块适配器（moduleAdapters）和核心适配器（coreModuleAdapters）。这种设计将工具发现逻辑与业务逻辑分离，便于扩展和维护。

graph TB
    subgraph "服务器模式层"
        A[Server Mode Enforcer] --> B[ModeConfigMapper]
        B --> C[Tool Catalog]
    end
    
    subgraph "工具加载层"
        C --> D[moduleAdapters]
        D --> E[coreModuleAdapters]
    end
    
    subgraph "工具注册层"
        E --> F[src/tools/*.ts]
        F --> G[MCP Server Tools]
    end
    
    subgraph "配置来源"
        H[--fmp-tool-sets] --> B
        I[--dynamic-tool-discovery] --> A
        J[环境变量 FMP_TOOL_SETS] --> B
    end

ModeConfigMapper 职责

ModeConfigMapper 是服务器模式实现的核心类，负责将配置映射为标准化的工具目录结构：

[key: ToolSet]: {
    name: string;
    description: string;
    decisionCriteria: string;
    modules: string[];
}

该映射器从两个来源解析工具集配置：当服务器模式为 STATIC_TOOL_SETS 时，从 Enforcer 级别配置读取工具集列表；其他模式下返回空数组，由动态发现机制处理。

资料来源：src/toolception-adapters/ModeConfigMapper.ts:70-77

模式配置方式

命令行参数配置

服务器支持通过命令行参数配置运行模式：

资料来源：server.json:23-50

环境变量配置

除命令行参数外，也可通过环境变量配置：

资料来源：server.json:51-78

会话级配置

客户端可在会话初始化时通过 session headers 设置个性化配置：

interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;
  FMP_TOOL_SETS?: string;
  DYNAMIC_TOOL_DISCOVERY?: string;
}

重要限制：根据 v2.6.7 版本的更新说明，会话配置目前仅支持 FMP_ACCESS_TOKEN 的动态设置，其他配置项必须在服务器级别预先配置。

资料来源：src/types/index.ts:37-42

工具集体系

系统定义了 24 种预配置工具集，每种工具集对应特定的金融数据域：

graph LR
    A[Tool Sets] --> B[quotes 报价数据]
    A --> C[statements 财务报表]
    A --> D[company 公司信息]
    A --> E[news 新闻]
    A --> F[analyst 分析师]
    A --> G[esg ESG评级]
    A --> H[technical-indicators 技术指标]
    A --> I[更多...]

完整工具集列表包括：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。

资料来源：src/types/index.ts:12-26

每种工具集包含四个属性：

• name：可读名称
• description：功能描述
• decisionCriteria：用户选择该工具集的决策依据
• modules：对应的底层模块数组

资料来源：src/constants/toolSets.ts 资料来源：src/types/index.ts:29-35

模式选择指南

已知限制与问题

Issue #100: batch-quote 端点误判

当前实现中存在一个计划级别验证的误判问题：batch-quote 端点会错误地拒绝 Ultimate 计划用户的请求。该错误发生在 MCP 层而非 FMP API 层，属于计划门控的误报。

Issue #93: 参数命名兼容性问题

工具输入模式使用了 Python 保留关键字（如 from）作为参数名，可能破坏 Python MCP 客户端的兼容性。v2.6.9 版本已部分修复，将 from 参数重命名为 from_date。

Issue #81: API Key 配置困难

用户反映在某些部署平台（如 Smithery）上设置 FMP API KEY 存在困难，配置后仍提示缺失令牌。

总结

服务器模式为 FMP MCP Server 提供了灵活的工具暴露策略。DYNAMIC_TOOL_DISCOVERY 模式适合需要运行时灵活性的场景，STATIC_TOOL_SETS 模式允许精细控制可用工具范围，而 ALL_TOOLS 模式则提供开箱即用的完整功能。选择合适的模式可优化资源使用并提升用户体验。

概述

Financial Modeling Prep MCP Server 提供了一套完整的金融数据访问工具集，通过 Model Context Protocol (MCP) 规范暴露给 AI 助手和自动化客户端。工具目录采用分层架构设计，将 FMP API 的全部功能组织为 24 个逻辑工具集（Tool Sets），每个工具集包含若干相关功能的 MCP 工具。

工具目录的核心价值在于：

• 模块化分组：将相似功能的 API 调用归类到同一工具集
• 按需加载：支持仅加载所需的工具集，减少资源消耗
• 权限隔离：基于 FMP 订阅计划进行工具访问控制
• 统一接口：通过 MCP 标准协议提供一致的调用体验

架构设计

工具集类型系统

工具集通过强类型系统定义，确保配置的一致性和编译时检查：

export type ToolSet =
  | "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";

资料来源：src/types/index.ts:22-47

工具集定义结构

每个工具集包含四个核心属性：

资料来源：src/types/index.ts:49-60

工具集分类

数据获取类

#### 搜索工具集 (search)

提供股票符号和公司搜索功能，是用户查找金融数据的入口点。

#### 公司信息工具集 (company)

访问公司基本信息和元数据。

#### 行情数据工具集 (quotes)

提供实时和历史价格数据。注意：Issue #100 报告了 batch-quote 端点对 Ultimate 计划用户的错误拦截问题，错误发生在 MCP 层而非 FMP API 层。

资料来源：src/tools/quotes.ts

财务报表类

#### 财务报表工具集 (statements)

提供四大财务报表及相关分析数据。

资料来源：src/tools/statements.ts

#### 财务分析工具集 (analyst)

整合分析师观点和评级数据。

市场数据类

#### 市场指数工具集 (indexes)

跟踪主要市场指数表现和成分股。

#### 大宗商品工具集 (commodities)

覆盖能源、金属和农产品期货数据。

#### 加密货币与外汇工具集 (crypto/forex)

提供数字资产和外汇市场数据。

另类数据类

#### ESG 与可持续发展工具集 (esg)

资料来源：src/constants/toolSets.ts

#### 机构持仓工具集 (institutional/form-13f)

跟踪机构投资者的持仓变化。

资料来源：src/tools/form-13f.ts

#### 内部交易工具集 (insider-trades)

监控公司内部人员的股票交易活动。数据类型定义包括：

interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}

资料来源：src/api/insider-trades/types.ts

#### 政府交易工具集 (senate)

追踪国会成员和参议员的股票交易披露。

#### SEC 文件工具集 (sec-filings)

提供监管文件和公司披露文档。

新闻与事件类

#### 新闻工具集 (news)

提供多来源金融新闻聚合。

新闻工具的参数模式已修复 Python 关键字冲突问题：

{
  from_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
  to: z.string().optional().describe("End date (YYYY-MM-DD)"),
  page: z.number().optional().describe("Page number (default: 0)"),
  limit: z.number().optional().describe("Limit on number of results")
}

资料来源：src/tools/news.ts

分析工具类

#### 技术指标工具集 (technical-indicators)

提供技术分析计算功能。

#### DCF 估值工具集 (dcf)

提供内在价值评估的现金流折现模型。

批量数据类

#### 批量数据工具集 (bulk)

支持大规模数据导出和批量查询，适用于数据仓库填充和历史分析。

工具集配置映射

ModeConfigMapper 类负责将 FMP 的服务器模式转换为 toolception 框架的配置格式：

graph TD
    A[FMP ServerMode] --> B{ModeConfigMapper.toToolceptionConfig}
    B --> C[DYNAMIC_TOOL_DISCOVERY]
    B --> D[STATIC_TOOL_SETS]
    B --> E[ALL_TOOLS]
    C --> F[Catalog + Dynamic Loaders]
    D --> G[Filtered Catalog]
    E --> H[Full Catalog]

资料来源：src/toolception-adapters/ModeConfigMapper.ts

参数命名规范

Python 兼容性问题修复

Issue #93 报告工具参数使用 Python 保留字导致 Python MCP 客户端无法正常工作。v2.6.9 已修复此问题：

此修复确保所有工具的 JSON Schema 与 Python 语法兼容。

资料来源：CHANGELOG.md - v2.6.9

配置与使用

环境变量配置

工具集白名单

在 toolception 配置中可通过 allowlist 指定允许的工具集：

exposurePolicy: {
  namespaceToolsWithSetKey: true,
  maxActiveToolsets: 10,
  allowlist: ["quotes", "news", "company"]
}

项目结构

资料来源：CONTRIBUTING.md

已知问题

扩展指南

添加新工具集

1. 在 src/constants/toolSets.ts 的 TOOL_SETS 对象中添加定义
2. 在 src/tools/ 创建对应的工具注册文件
3. 在 src/toolception-adapters/moduleAdapters.ts 添加适配器
4. 更新 src/types/index.ts 中的 ToolSet 联合类型

添加新工具

1. 在 src/api/{domain}/ 的客户端中添加方法
2. 在对应模块的 src/tools/{module}.ts 中注册工具
3. 使用 Zod schema 定义参数验证

详细步骤请参考 docs/USAGE.md。

工具系统概述

FMP MCP Server 通过 Model Context Protocol (MCP) 向 AI 助手暴露 Financial Modeling Prep API 的所有功能。工具系统采用模块化架构，将相关的 API 端点分组为不同的工具集。

核心设计原则：

• 永不抛异常：工具处理函数必须捕获所有错误并返回 { content: [...], isError: true } 格式的响应
• 全局唯一命名：工具名称必须在所有28个模块中保持唯一
• 统一注解：所有工具使用相同的注解：readOnlyHint、idempotentHint、openWorldHint
• 参数兼容性：参数名不能使用 Python 保留关键字（如 from 已改为 from_date）

资料来源：src/tools/AGENTS.md

24个工具集

系统支持24个功能模块，涵盖股票行情、财务数据、新闻、技术分析等金融数据领域：

资料来源：src/constants/toolSets.ts 资料来源：src/types/index.ts

工具使用流程

graph TD
    A[MCP客户端] --> B[工具调用请求]
    B --> C{MCP Server}
    C --> D{工具集权限检查}
    D -->|已授权| E[执行工具逻辑]
    D -->|未授权| F[返回权限错误]
    E --> G[调用FMP API]
    G --> H{API响应}
    H -->|成功| I[返回JSON数据]
    H -->|失败| J[捕获异常]
    J --> K[返回错误响应]
    I --> L[格式化输出]
    K --> L
    L --> M[MCP客户端]

参数规范

所有工具参数使用 Zod 进行模式验证。参数命名需要遵循以下规则：

日期参数命名规则：

• 使用 from_date 而非 from（避免 Python 保留关键字冲突）
• 使用 to_date 或 to 表示结束日期

标准参数模式：

server.tool(
  "toolName",
  "工具描述，说明功能和使用场景",
  {
    // 必选参数
    symbol: z.string().describe("股票代码，如 AAPL"),
    
    // 可选参数
    from_date: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
    to_date: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
    limit: z.number().optional().describe("返回结果数量限制"),
    page: z.number().optional().describe("分页页码"),
  },
  async ({ symbol, from_date, to_date, limit, page }) => {
    // 工具实现
  }
);

资料来源：src/tools/news.ts 资料来源：src/tools/AGENTS.md

错误处理规范

严格禁止在工具处理函数中抛出异常。MCP 协议要求错误通过响应体返回，而非异常机制。

正确的错误处理模式：

async ({ symbol, limit }) => {
  try {
    const results = await apiClient.getData({ symbol, limit });
    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,
    };
  }
}

错误消息格式要求：

• 必须以 Error: 开头
• 保持一致的性格化输出

资料来源：src/tools/AGENTS.md 资料来源：src/tools/news.ts

常见使用问题

Python 保留关键字问题

问题描述：部分工具参数名使用了 Python 保留关键字（如 from、class），导致 Python MCP 客户端无法正确解析。

解决方案：v2.6.9 版本已将 from 参数重命名为 from_date。如遇到其他保留关键字问题，请参考以下映射：

资料来源：CHANGELOG.md

API Key 配置问题

问题描述：用户报告在 Smithery.ai 集成时无法设置 FMP_API_TOKEN。

解决方案：

• 使用环境变量 FMP_ACCESS_TOKEN（不是 FMP_API_TOKEN）
• 在会话级别，只能设置 FMP_ACCESS_TOKEN，其他配置项仅支持服务器级别

// 正确的配置方式
FMP_ACCESS_TOKEN=your_token_here

资料来源：src/types/index.ts

批量报价权限问题

问题描述：batch-quote 端点对 Ultimate 计划用户返回 ACCESS DENIED 错误。

说明：这是已知的 MCP 层计划门控误报问题，错误发生在 MCP 层而非 FMP API 层。问题会在后续版本中修复。

添加新工具

如需扩展工具集，请按照以下步骤操作：

流程概览：

graph LR
    A[添加API客户端方法] --> B[注册工具]
    B --> C[添加适配器]
    C --> D[映射到工具集]
    D --> E[测试工具]

详细步骤：

工具注册示例：

server.tool(
  "toolName",
  "工具描述",
  {
    paramName: z.string().describe("参数说明"),
  },
  async ({ paramName }) => {
    try {
      const result = await client.getData({ paramName });
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      return {
        content: [
          { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` },
        ],
        isError: true,
      };
    }
  }
);

资料来源：GUIDE.md

数据类型参考

内部人员交易数据

interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}

DCF 估值数据

interface DCFData {
  revenue?: number;
  netIncome?: number;
  operatingCashFlow?: number;
  freeCashFlow?: number;
  wacc?: number;
  terminalValue?: number;
  enterpriseValue?: number;
  equityValue?: number;
  equityValuePerShare?: number;
  price?: number;
  beta?: number;
}

资料来源：src/api/insider-trades/types.ts 资料来源：src/api/dcf/types.ts

工具集决策指南

根据用户需求选择合适的工具集：

安装与初始配置

Node.js 版本要求不满足

症状: 服务器启动时报错 node: command not found 或版本不兼容错误。

解决方案: 本服务器要求 Node.js >= 25.3.0 和 npm >= 11.11.0。请升级 Node.js：

# 使用 nvm 升级 Node.js
nvm install 25.3.0
nvm use 25.3.0

# 验证版本
node --version  # 应显示 v25.3.0 或更高
npm --version   # 应显示 11.11.0 或更高

资料来源：package.json:47-48

API 密钥配置失败

症状: 连接服务器时收到 "ACCESS DENIED" 或 "missing FMP_ACCESS_TOKEN" 错误。

原因分析: 根据 Issue #81 的用户反馈，在 Smithery.ai 等平台配置时，可能出现 OAuth 字段留空后 API Token 无法传递的问题。

解决方案:

# 方式一：环境变量
export FMP_ACCESS_TOKEN=your_api_token_here
fmp-mcp

# 方式二：命令行参数
fmp-mcp --fmp-token your_api_token_here

资料来源：server.json:19-22

重要说明: sessionConfig 参数仅允许设置 FMP_ACCESS_TOKEN 字段，不支持其他自定义字段的会话级配置。资料来源：CHANGELOG.md

Docker 安装配置问题

症状: Docker 容器无法正常启动或认证失败。

解决方案: 从源码构建镜像而非使用预构建镜像：

# 构建本地镜像
docker build -t fmp-mcp-local .

# 运行容器
docker run -e FMP_ACCESS_TOKEN=your_token fmp-mcp-local

资料来源：CHANGELOG.md:39-41

工具使用问题

Python 保留关键字导致客户端解析失败

症状: Python MCP 客户端（如 LangChain、Claude SDK 等）无法正确调用工具，参数验证失败。

原因分析: Issue #93 报告了多个工具的参数名称使用了 Python 保留关键字，违反了 JSON Schema 到 Python 类型的转换规范。

受影响的参数:

版本修复: v2.6.9 已将 from 参数重命名为 from_date：

// 修复前 (v2.6.8)
{ from: z.string().optional() }

// 修复后 (v2.6.9+)
{ from_date: z.string().optional().describe("Start date (YYYY-MM-DD)") }

资料来源：src/tools/news.ts:1-50 资料来源：CHANGELOG.md:24-27

batch-quote 端点计划级别误判

症状: Ultimate 计划用户访问 batch-quote 相关工具时返回 "ACCESS DENIED - lower-tier plan" 错误。

原因分析: Issue #100 报告此问题由 MCP 层在请求到达 FMP API 前就进行了错误的计划验证，导致合法用户被错误拦截。

排查步骤:

1. 确认 FMP 账户当前订阅计划为 Ultimate
2. 检查 API Token 是否具有批量查询权限
3. 验证 token 未过期或被撤销
4. 联系 FMP 支持确认账户权限状态

临时解决方案: 使用单个股票报价工具替代批量查询，逐个获取数据。

资料来源：Issue #100

工具集未加载或不可用

症状: 尝试调用特定工具时报错 "Tool not found" 或功能完全不可用。

原因分析: 服务器可能运行在 STATIC_TOOL_SETS 模式，仅加载配置的工具集。

解决方案: 检查并配置 FMP_TOOL_SETS 参数：

# 启动时指定工具集
fmp-mcp --fmp-tool-sets quotes,company,statements

# 或使用环境变量
export FMP_TOOL_SETS="quotes,company,statements"

可用工具集列表:

资料来源：src/constants/toolSets.ts 资料来源：src/types/index.ts:24-47

数据类型与响应问题

返回数据类型定义

NewsArticle 类型结构:

资料来源：src/api/news/types.ts:14-21

FMPArticle 类型结构:

资料来源：src/api/news/types.ts:3-12

Insider 交易数据字段

资料来源：src/api/insider-trades/types.ts:1-18

服务器模式配置

三种服务器模式详解

graph TD
    A[服务器启动] --> B{启动参数配置}
    B --> C[ALL_TOOLS]
    B --> D[STATIC_TOOL_SETS]
    B --> E[DYNAMIC_TOOL_DISCOVERY]
    
    C --> F[加载全部 250+ 工具]
    D --> G[仅加载指定工具集]
    E --> H[运行时动态发现]
    
    F --> I[完整功能但资源占用高]
    G --> J[按需加载灵活性高]
    H --> K[智能按需加载]

资料来源：src/types/index.ts:49-51 资料来源：src/toolception-adapters/ModeConfigMapper.ts

ModeConfigMapper 配置映射

ModeConfigMapper 类负责将 FMP 服务器模式转换为 toolception 框架配置：

interface ToolceptionConfig {
  catalog: ToolSetCatalog;       // 工具集目录
  moduleLoaders: Record<string, ModuleLoader>;  // 模块加载器
  startup: { mode: 'DYNAMIC' | 'STATIC' };
  context: { accessToken?: string };
  exposurePolicy: {
    namespaceToolsWithSetKey: boolean;
    maxActiveToolsets?: number;
    allowlist?: ToolSet[];
  };
}

资料来源：src/toolception-adapters/ModeConfigMapper.ts:44-56

调试与诊断

启用调试模式

# 查看所有可用的工具集
fmp-mcp --help

# 验证配置
npm run version:validate

# 检查版本一致性
npm run version:info

常见错误码对照表

诊断流程图

graph TD
    A[遇到问题] --> B{错误类型?}
    B --> C[认证错误]
    B --> D[工具不可用]
    B --> E[数据错误]
    B --> F[性能问题]
    
    C --> C1{Token 配置正确?}
    C1 -->|否| C2[配置 API Token]
    C1 -->|是| C3[检查 Token 权限]
    
    D --> D1{工具集配置?}
    D1 -->|未配置| D2[配置 FMP_TOOL_SETS]
    D1 -->|已配置| D3[检查模块加载器]
    
    E --> E1{返回数据结构?}
    E1 -->|异常| E2[查看 API 文档]
    E1 -->|错误| E3[检查网络连接]
    
    F --> F1{延迟高?}
    F1 -->|是| F2[启用动态工具发现]
    F1 -->|否| F3[优化请求批次]

获取帮助

资源链接

报告问题

报告新问题时请包含以下信息：

1. 服务器版本 (npm list financial-modeling-prep-mcp-server)
2. Node.js 版本 (node --version)
3. 完整的错误日志
4. 复现步骤
5. 环境配置（隐藏敏感信息如 API Token）

Pitfall Log / 踩坑日志

项目：imbenrabi/financial-modeling-prep-mcp-server

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients。

1. 安装坑 · 来源证据：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_75b7a65ba21a4165943ec8a7ebcd0091 | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：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. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：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. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：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. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：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

6. 安全/权限坑 · 来源证据：FMP API KEY impossible to set

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FMP API KEY impossible to set
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9ae13b6fa15041539df40160e45bb1b0 | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/81 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

7. 安全/权限坑 · 来源证据：batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e69c7ecfae6b40be92a4af0220588aaf | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/100 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：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

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：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