MCP 服务器

Financial Modeling Prep MCP Server

cdtait

研究与数据

访问服务器

README

Financial Modeling Prep MCP 服务器

一个模型上下文协议 (MCP) 服务器，它提供使用 Financial Modeling Prep API 进行财务分析的工具、资源和提示。

特性

公司信息: 访问详细的公司概况和同行比较
财务报表: 检索和分析利润表、资产负债表和现金流量表
财务指标: 访问用于投资分析的关键财务比率和指标
市场数据: 获取市场快照、指数和新闻
股票报价: 获取当前股票报价和简化的价格信息
股票图表: 访问历史价格数据并计算价格变化
分析师评级: 获取分析师建议和评级详情
市场指数: 访问市场指数数据和报价
市场表现者: 获取涨幅最大、跌幅最大和交易最活跃的股票
市场交易时间: 查看主要交易所的市场交易时间和节假日
ETF 分析: 分析 ETF 行业权重、国家风险敞口和持仓
商品: 获取商品列表和当前价格
加密货币: 访问加密货币列表和当前报价
外汇: 获取外汇货币对列表和汇率
技术指标: 计算和解释技术指标并获取技术分析摘要
分析提示: 使用预定义的提示模板生成投资分析
聊天代理: 与 FMP MCP 服务器进行交互式 CLI 聊天界面

代码组织

代码库的组织结构与 FMP API 文档结构一致，可在 FMP API 文档中找到。每个模块对应于 API 的特定部分：

analyst.py: 分析师建议和目标价格
charts.py: 股票图表和历史价格数据
commodities.py: 商品列表和价格数据
company.py: 公司概况和相关信息
crypto.py: 加密货币列表和报价
etf.py: ETF 行业权重、国家风险敞口和持仓
forex.py: 外汇货币对列表和汇率
indices.py: 市场指数列表和报价
market.py: 市场数据和新闻
market_hours.py: 主要交易所的市场交易时间和节假日
market_performers.py: 涨幅最大、跌幅最大和交易最活跃的股票
quote.py: 股票报价数据和价格变化
search.py: 用于搜索股票代码和公司的 API
statements.py: 财务报表（收入、资产负债表、现金流量、比率）
technical_indicators.py: 技术指标和分析

API 端点标准化

该代码库使用标准化方法来检索不同资产类型的报价：

统一的 quote 端点用于检索所有资产类型的报价，包括：
- 股票
- 外汇货币对
- 加密货币
- 商品
- 市场指数
每个模块都为其各自的资产类型提供专门的格式：
- get_quote: 标准股票报价
- get_forex_quotes: 货币汇率
- get_crypto_quote: 加密货币价格
- get_commodities_prices: 商品价格
- get_index_quote: 市场指数值

这种标准化提高了代码的可维护性，并为在整个应用程序中检索资产价格提供了一致的方法。

其他最近的更改

get_quote_change: 更新为使用 "stock-price-change" 端点而不是 "quote-change" 端点
- 现在在单个请求中返回所有时间段（1D、5D、1M、3M、6M、YTD、1Y、3Y、5Y、10Y、max）的价格变化
- 改进了表格格式，以提高可读性
- 表情符号指示器 (🔺, 🔻, ➖) 用于更清晰的趋势可视化

测试的组织方式类似，每个模块一个测试文件，遵循一致的模式以确保全面的覆盖。

安装

克隆存储库
使用 uv 设置环境：

# 如果您还没有 uv，请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH=~/.local/bin/:${PATH}

# 创建并激活环境
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖项
uv pip install -e .

设置您的 Financial Modeling Prep API 密钥：

# 复制模板
cp .env.template .env

# 编辑 .env 文件以添加您的 API 密钥
# 将 'your_api_key_here' 替换为您从 FMP 获得的实际 API 密钥

您可以通过在 Financial Modeling Prep 注册来获取 API 密钥。

设置您的 OpenAI API 密钥（如果使用聊天代理）：

# 将您的 OpenAI API 密钥添加到 .env 文件
echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env

开发

该项目遵循测试驱动开发 (TDD) 方法。测试套件组织在 tests/ 目录中。

测试策略

该项目实施了全面的测试策略，包含三种不同的测试类型：

单元测试 (test_company.py, test_quotes.py 等)
- 专注于隔离测试单个函数
- 按模块组织以匹配代码结构
- 模拟所有外部依赖项
- 验证正常操作、边缘情况和错误处理的正确行为
- 快速执行且没有外部依赖项
- 使用 @patch 装饰器进行模拟，遵循一致的模式
- 在修补后导入函数以确保正确的模拟隔离
集成测试 (test_server.py, test_resources.py)
- 测试组件如何协同工作
- 验证正确的服务器设置、工具注册和资源处理
- 使用模拟的外部 API 测试端到端流程
- 确保系统组件正确集成
- 验证组件之间正确的错误处理
验收测试 (acceptance_tests.py)
- 验证与真实 FMP API 的集成
- 验证 API 连接和响应格式
- 使用无效输入测试错误处理
- 专注于数据结构而不是特定值
- 可以在真实 API 模式下运行，也可以使用 TEST_MODE=true 运行模拟数据
- 仅在显式触发或提供 API 密钥时才使用真实 API 运行

这种多层次的方法使人们对单个组件和整个系统都充满信心，确保应用程序在隔离状态下以及与真实 API 集成时都能正常工作。

运行测试

# 运行所有单元测试和集成测试
pytest

# 运行并生成覆盖率报告
pytest --cov=src tests/

# 运行特定的测试文件
pytest tests/test_company.py

# 运行带有特定标记的测试
pytest -m acceptance

验收测试

该项目包括验收测试，用于验证与真实 FMP API 的集成。这些测试需要有效的 API 密钥，也可以使用模拟数据运行。

要运行验收测试：

# 选项 1：使用真实 API 运行
# 设置您的 API 密钥
export FMP_API_KEY=your_api_key_here

# 使用真实 API 运行验收测试
pytest tests/acceptance_tests.py -v

# 选项 2：使用模拟数据运行
# 这不需要 API 密钥，并使用模拟响应
export TEST_MODE=true
pytest tests/acceptance_tests.py -v

这些测试验证：

API 连接
数据格式和结构
使用无效输入的错误处理
使用真实数据的工具格式

验收测试旨在检查格式和结构，而不断言可能随时间变化（如股票价格）的特定值。这使得它们适合于具有有效 API 密钥机密的 CI/CD 管道。

使用 TEST_MODE=true 可以在 CI 环境中运行验收测试，而无需真实的 API 密钥，而是使用在 conftest.py 中定义的模拟响应。

项目结构

fmp-mcp-server/
├── src/                      # 源代码
│   ├── api/                  # API 客户端功能
│   │   ├── client.py         # FMP API 客户端
│   ├── tools/                # MCP 工具实现
│   │   ├── analyst.py        # 分析师评级工具
│   │   ├── charts.py         # 股票图表工具
│   │   ├── commodities.py    # 商品工具
│   │   ├── company.py        # 公司概况工具
│   │   ├── crypto.py         # 加密货币工具
│   │   ├── etf.py            # ETF 分析工具
│   │   ├── forex.py          # 外汇工具
│   │   ├── indices.py        # 市场指数工具
│   │   ├── market.py         # 市场数据工具
│   │   ├── market_hours.py   # 市场交易时间工具
│   │   ├── market_performers.py # 市场表现者工具
│   │   ├── quote.py          # 股票报价工具
│   │   ├── search.py         # 搜索工具
│   │   ├── statements.py     # 财务报表工具
│   │   └── technical_indicators.py # 技术分析工具
│   ├── resources/            # MCP 资源实现
│   │   ├── company.py
│   │   └── market.py
│   ├── prompts/              # MCP 提示实现
│   │   └── templates.py
│   └── agent_chat_client.py  # 基于 OpenAI Agent 的聊天客户端
├── tests/                    # 测试套件
│   ├── conftest.py           # Pytest fixtures
│   ├── acceptance_tests.py   # API 集成测试
│   ├── test_analyst.py       # 分析师工具的测试
│   ├── test_api_client.py    # API 功能的测试
│   ├── test_calendar.py      # 日历工具的测试
│   ├── test_charts.py        # 图表工具的测试
│   ├── test_commodities.py   # 商品工具的测试
│   ├── test_company.py        # 公司概况工具的测试
│   ├── test_crypto.py         # 加密货币工具的测试
│   ├── test_etf.py            # ETF 工具的测试
│   ├── test_forex.py         # 外汇工具的测试
│   ├── test_indices.py       # 指数工具的测试
│   ├── test_market.py         # 市场工具的测试
│   ├── test_market_hours.py  # 市场交易时间工具的测试
│   ├── test_market_performers.py # 市场表现者工具的测试
│   ├── test_prompts.py       # 提示的测试
│   ├── test_quotes.py        # 报价工具的测试
│   ├── test_resources.py     # 资源的测试
│   ├── test_search.py        # 搜索工具的测试
│   ├── test_server.py        # 集成测试
│   ├── test_statements.py    # 财务报表工具的测试
│   └── test_technical_indicators.py # 技术指标工具的测试
├── Dockerfile                # Docker 配置
├── docker-compose.yml        # Docker Compose 配置
└── server.py                 # 主服务器实现

用法

运行服务器

您可以通过不同的方式运行服务器：

本地开发 (stdio)

# 直接运行服务器 (stdio 模式)
python -m src.server

# 或者使用 MCP CLI 进行开发
mcp dev src/server.py

# 安装在 Claude Desktop 中
mcp install src/server.py

SSE 服务器模式

# 作为 SSE 服务器运行
python -m src.server --sse --port 8000

这将在 SSE（服务器发送事件）模式下启动服务器，允许通过 HTTP 连接 MCP Inspector 或其他 MCP 客户端。

使用聊天代理

该项目包括一个聊天代理，它通过 SSE 连接到 FMP MCP 服务器，并提供一个交互式 CLI 界面用于财务数据查询。

前提条件

OpenAI API 密钥（在您的环境或 .env 文件中设置）
在 SSE 模式下运行的 FMP MCP 服务器

运行聊天代理

在 SSE 模式下启动 FMP MCP 服务器：

# 在一个终端窗口中
python -m src.server --sse

在另一个终端窗口中，运行聊天代理：

# 确保您已设置 OpenAI API 密钥
export OPENAI_API_KEY=your_openai_api_key_here

# 运行聊天代理
python src/agent_chat_client.py

开始与财务顾问代理聊天：

查看跟踪：https://platform.openai.com/traces/trace?trace_id=trace_abc123...

您：苹果的当前价格是多少？
正在运行：苹果的当前价格是多少？
苹果公司 (AAPL) 的当前价格为 $202.52。

您：比较 AAPL 和 MSFT 的财务业绩
正在运行：比较 AAPL 和 MSFT 的财务业绩
...

聊天代理功能

与 FMP 财务数据进行交互式聊天界面
通过自然语言访问所有 FMP 数据工具
基于 OpenAI Agent 的实现，用于复杂的查询
跟踪视图，用于调试和理解代理操作

键入 exit 或 quit 以结束聊天会话。

使用 Docker

有几种方法可以使用 Docker 运行服务器：

选项 1：在本地构建和运行

# 使用 Docker 构建和运行
docker build -t fmp-mcp-server .
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here fmp-mcp-server

# 或者使用 docker-compose 和默认端口 (8000)
# 方法 1：导出环境变量（安全性较低）
export FMP_API_KEY=your_api_key_here
docker-compose up

# 方法 2（首选）：使用 .env 文件（更安全）
# 首先，在项目根目录中创建一个包含您的 API 密钥的 .env 文件
echo "FMP_API_KEY=your_api_key_here" > .env
docker-compose up

# 使用带有自定义端口的 docker-compose
# 使用环境变量
PORT=9000 docker-compose up

# 同时使用 .env 文件和自定义端口
echo "FMP_API_KEY=your_api_key_here" > .env
PORT=9000 docker-compose up

选项 2：使用 GitHub Container Registry 中预构建的镜像

# 拉取最新镜像
docker pull ghcr.io/cdtait/fmp-mcp-server:latest

# 使用环境变量运行 API 密钥
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# 使用自定义端口运行
docker run -p 9000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# 使用挂载的 .env 文件运行（首选）
# 首先使用您的 API 密钥创建您的 .env 文件
echo "FMP_API_KEY=your_api_key_here" > .env

# 然后在运行容器时挂载它
docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

服务器将始终在容器内的端口 8000 上侦听，但 Docker 会将其映射到指定的宿主机端口（默认 8000 或 PORT 环境变量的值）。

注意： 最好使用 .env 文件方法来存储您的 API 密钥，而不是在您的 shell 中导出它，因为它降低了在您的命令历史记录或环境变量中意外泄漏密钥的风险。

使用 MCP Inspector

MCP Inspector 是一个用于测试您的 MCP 服务器的有用工具。您可以使用它来浏览可用的工具、资源和提示，并以交互方式测试它们。

使用 Node.js 运行 MCP Inspector

运行 MCP Inspector 的最简单方法是使用 Node.js：

# 使用 npx（无需安装）
npx @modelcontextprotocol/inspector

# 或者如果您已全局安装该软件包
mcp-inspector

MCP Inspector 运行后：

在 Transport 下拉列表中，选择 "HTTP/SSE"
输入您的服务器 URL：http://localhost:8000/sse
- 如果您使用自定义端口启动服务器（例如，PORT=9000），请改用该端口：http://localhost:9000/sse
单击 "Connect" 以建立与您的服务器的连接
在各自的选项卡中浏览可用的工具、资源和提示

使用 Python 运行 MCP Inspector

如果您更喜欢使用 Python，可以使用 MCP CLI：

# 如果您尚未安装 MCP CLI，请安装它
pip install mcp-cli

# 运行 inspector（使用默认端口）
mcp inspect http://localhost:8000

# 或者使用您指定的自定义端口
mcp inspect http://localhost:9000

示例查询

服务器运行并连接到 MCP 客户端（如 Claude Desktop 或 MCP Inspector）后，您可以：

获取公司概况：
- "使用公司概况工具告诉我关于苹果公司的财务概况"
- "TSLA 的关键财务指标是什么？"
获取财务报表：
- "显示我 AAPL 去年的利润表"
- "TSLA 的资产负债表是什么？"
- "获取 MSFT 的现金流量表并分析它"
获取股票报价和价格信息：
- "MSFT 股票的当前价格是多少？"
- "显示我 GOOGL 最近的价格变化"
- "比较 AAPL、AMZN 和 META 的当前报价"
获取分析师评级：
- "分析师如何看待 AMZN 股票？"
- "给我 NVDA 的分析师评级快照"
- "显示我 MSFT 的最新目标价格"
获取市场指数和表现者：
- "显示我当前的主要市场指数"
- "今天涨幅最大的股票是什么？"
- "今天市场上交易最活跃的股票是哪些？"
检查市场状态：
- "市场现在开盘了吗？"
- "下一个市场假期是什么时候？"
- "纽约证券交易所的交易时间是什么时候？"
分析 ETF：
- "SPY 的前几大持仓是什么？"
- "显示我 QQQ 的行业细分"
- "VEU 对哪些国家有风险敞口？"
获取商品、加密货币和外汇信息：
- "黄金的当前价格是多少？"
- "显示我当前的比特币价格"
- "EURUSD 的汇率是多少？"
获取技术分析：
- "计算 AAPL 的 RSI"
- "给我 TSLA 的技术分析摘要"
- "20 天 SMA 告诉我们关于 AMZN 的什么？"
使用分析提示：
- "使用股票比较提示比较 AAPL、MSFT 和 GOOGL"
- "使用财务报表分析提示分析 TSLA 的财务报表"

配置

服务器使用以下环境变量：

FMP_API_KEY: 您的 Financial Modeling Prep API 密钥（必需）
- 您可以通过在 Financial Modeling Prep 注册来获取 API 密钥
- 可以通过命令行、环境变量或 .env 文件传递
OPENAI_API_KEY: 您的 OpenAI API 密钥（使用聊天代理需要）
- 从 OpenAI 获取 API 密钥
PORT: 使用 Docker Compose 运行时要使用的宿主机端口（默认为 8000）
- 仅影响宿主机端口映射，容器始终在内部端口 8000 上运行
TEST_MODE: 设置为 "true" 以在验收测试中使用模拟数据
- 适用于 CI/CD 环境或在没有有效 API 密钥的情况下进行测试
- 使用 tests/conftest.py 中定义的模拟响应
- 包括各种资产类型的全面模拟数据：
  - 股票（AAPL、MSFT 等）
  - 外汇货币对（EURUSD、GBPUSD、USDJPY）
  - 加密货币（BTCUSD、ETHUSD）
  - 商品（GCUSD 代表黄金，CLUSD 代表原油，BZUSD 代表布伦特原油）
  - 市场指数（^GSPC 代表标准普尔 500 指数，^DJI 代表道琼斯指数）

您可以在项目根目录的 .env 文件中设置这些变量：

# 示例 .env 文件内容
FMP_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
PORT=9000
TEST_MODE=true  # 用于使用模拟数据进行测试

贡献

创建一个功能分支
为您的功能编写测试
实现您的功能，确保测试通过
提交拉取请求

CI/CD 管道

该项目实施了包含多个阶段的全面 CI/CD 管道：

1. 持续集成 (ci.yml)

每次拉取请求和推送到 main 都会自动触发：

单元测试: 使用 pytest 测试单个组件
- 在多个 Python 版本 (3.11, 3.12) 上运行
- 排除验收测试
- 将覆盖率报告给 Codecov
集成测试: 验证组件交互
- 使用 TEST_MODE=true 运行验收测试
- 使用模拟数据以避免 API 成本
- 报告单独的覆盖率指标
部署（合并到 main 时）：
- 使用最新代码构建 Docker 镜像
- 发布到 GitHub Container Registry
- 创建用于跟踪的部署标记

工作流程配置位于 .github/workflows/ci.yml 中。

2. 验收测试 (acceptance-tests.yml)

使用真实 FMP API 进行测试：

计划: 自动在每个星期一 UTC 时间凌晨 5 点运行
按需: 可以使用特定提交手动触发
验证: 确认真实 API 兼容性
状态更新: 记录部署的成功/失败

这个单独的工作流程有助于确保与外部 API 的兼容性，同时保持主 CI 管道快速并避免不必要的 API 成本。

要手动运行验收测试工作流程：

转到 GitHub 存储库
单击 "Actions" 选项卡
从工作流程列表中选择 "API Acceptance Tests"
单击 "Run workflow"（可以选择指定提交 SHA）

验收测试工作流程配置位于 .github/workflows/acceptance-tests.yml 中。

3. 发布过程 (release.yml)

准备好发布稳定版本时：

手动触发: 提供版本号和提交 SHA
验证: 确保提交已通过验收测试
标记: 创建 Git 标签和 GitHub 发布
生产镜像: 发布版本化和稳定的 Docker 镜像

要创建新版本：

转到 GitHub 存储库
单击 "Actions" 选项卡
从工作流程列表中选择 "Release"
单击 "Run workflow"
输入要发布的版本号和提交 SHA

发布工作流程配置位于 .github/workflows/release.yml 中。

容器注册表

Docker 镜像以各种标签发布到 GitHub Container Registry：

# 开发（来自 CI 管道）
docker pull ghcr.io/cdtait/fmp-mcp-server:latest           # 来自 main 分支的最新构建
docker pull ghcr.io/cdtait/fmp-mcp-server:a7f33fe2ce0265e0 # 特定提交

# 生产版本（来自发布工作流程）
docker pull ghcr.io/cdtait/fmp-mcp-server:stable           # 最新稳定版本
docker pull ghcr.io/cdtait/fmp-mcp-server:v1.2.3           # 特定版本

有关运行容器的详细说明，请参阅使用 Docker 部分。

覆盖率报告

代码覆盖率在不同的测试阶段进行跟踪：

单元测试: 基本代码路径覆盖率
集成测试: 使用模拟数据的覆盖率
验收测试: 使用真实 API 调用的覆盖率

Codecov 用于聚合和可视化覆盖率指标，每个测试阶段都有单独的标志。