Financial Modeling Server

MCP财务建模准备服务器

 ](https://github.com/cplim/cc-python-mcp-fcp/actions/workflows/docker.yml)

模型上下文协议（MCP）服务器，使用财务建模准备API为财务分析提供工具、资源和提示。

特性

✅ 目前已实施

• 公司简介数据：获取详细的公司信息，包括行业、网站和描述
• 利润表：检索包含收入、利润和运营指标的公司财务报表
• 实时股票报价：获取当前股票价格、变化和每日/年度范围
• 历史股价：通过可选的日期范围过滤获取历史价格数据
• 市场指数：获取当前价格和变化的市场指数数据（标准普尔500指数、纳斯达克指数、道琼斯指数）
• 交易量：获取交易量数据，包括当前和平均交易量
• 财务比率：全面的比率分析，包括流动性、盈利能力和杠杆比率
• DCF估值：贴现现金流估值，包括上行/下行分析
• 技术指标：技术分析工具，包括SMA、EMA、RSI、MACD等
• 增强型DCF分析：具有杠杆DCF、情景建模和财务健康评分的高级DCF
• 高级财务健康：Altman Z-Score、Piotroski F-Score和综合财务实力分析
• 模式驱动架构：所有服务的基于JSON的模式定义
• 服务体系结构：通过显式依赖注入实现干净、可维护的服务抽象
• 错误处理：针对API故障和无效输入的全面错误处理
• 数据验证：所有财务数据的配置驱动输入验证和格式化输出

🚧 计划的功能

• ESG数据：环境、社会和治理评级
• 内幕交易：追踪内幕交易
• 高级分析：分析师估计和盈利预测

📋 MCP资源和提示

• 基于模式的：资源和提示从JSON配置文件加载
• 资源：3个财务分析模板（可配置）

- financial://templates/analysis：综合财务分析模板 - financial://templates/report：财务报告生成模板 - financial://templates/company：公司分析模板

• 提示：3个结构化财务分析工作流（可配置）

- analyze_company：完成公司财务业绩分析 - technical_analysis：带有指标和趋势的技术分析 - financial_health：使用比率和指标进行财务健康评估

• 建筑：工具（动态服务）和资源/提示（静态配置）之间的清晰分离

安装

本地安装

uv add mcp-financial-modeling-prep

Docker安装

选项1：使用预构建图像（推荐）

# Pull from GitHub Container Registry
docker pull ghcr.io/cplim/cc-python-mcp-fcp:latest

# Run with environment variable (recommended)
docker run -e FMP_API_KEY=your_api_key_here -p 8000:8000 ghcr.io/cplim/cc-python-mcp-fcp:latest

# Test the server
curl http://localhost:8000/health

选项2：本地构建

# Build the Docker image locally
docker build -t mcp-financial .

# Run with environment variable (recommended)
docker run -e FMP_API_KEY=your_api_key_here -p 8000:8000 mcp-financial

# Or run with bind-mounted .env file
echo "FMP_API_KEY=your_api_key_here" > .env
docker run -v $(pwd)/.env:/app/.env -p 8000:8000 mcp-financial

可用标签：

• latest -主分支最新稳定构建
• v1.0.0 -特定版本发布（即将发布）
• feature-* -功能分支构建（用于测试）

看 码头长期使用.md 了解详细的Docker使用示例和传输选项。

配置

设置财务建模准备API键：

export FMP_API_KEY="your_api_key_here"

用法

MCP服务器支持 双传输协议 对于不同的部署场景：

标准传输（默认-用于子流程）

# Make sure you have the FMP_API_KEY environment variable set
export FMP_API_KEY="your_api_key_here"

# Run with stdio transport (default)
python -m mcp_financial_modeling_prep.server --transport stdio
# or simply
python -m mcp_financial_modeling_prep.server

HTTP传输（用于容器化/网络部署）

# Run with HTTP transport on port 8000
python -m mcp_financial_modeling_prep.server --transport http --port 8000

# Access health check
curl http://localhost:8000/health

# Access server info
curl http://localhost:8000/info

Docker使用

# Run with HTTP transport (recommended for containers)
docker run -p 8000:8000 -e FMP_API_KEY=your_key_here ghcr.io/cplim/cc-python-mcp-fcp:latest

# Health check
curl http://localhost:8000/health

可用工具

1. get_company.profile：获取详细的公司信息

- 输入： {"symbol": "AAPL"} - 返回：包含名称、行业、网站和描述的格式化公司简介

1. get_come_statement：获取公司财务报表

- 输入： {"symbol": "AAPL"} - 回报：包含收入、利润和关键指标的格式化损益表

1. get_stock_quote：获取实时股票报价

- 输入： {"symbol": "AAPL"} - 回报：包含价格、变动和交易范围的格式化股票报价

1. 获取历史价格：获取历史股价数据

- 输入： {"symbol": "AAPL", "from_date": "2023-01-01", "to_date": "2023-12-31"} - 回报：包含开盘价、高点、低点、收盘价和成交量数据的格式化历史价格

1. get_market_indexs：获取市场指数信息

- 输入： {} （无需参数） - 回报：包含当前价格和变化的格式化市场指数数据

1. get_trading_volume：获取交易量数据

- 输入： {"symbol": "AAPL"} - 回报：当前和平均交易量的格式化交易量

1. 获取财务比率：获取全面的财务比率分析

- 输入： {"symbol": "AAPL"} - 回报：包括流动性、盈利能力和杠杆率在内的格式化财务比率

1. get_dcf_值：获取DCF估值分析

- 输入： {"symbol": "AAPL"} - 回报：采用公允价值和上行/下行分析的格式化DCF估值

1. get_技术指标：获取技术分析指标

- 输入： {"symbol": "AAPL", "indicator_type": "sma", "period": 20, "timeframe": "1day"} - 回报：包含历史数据和分析的格式化技术指标 - 支持多种时间范围：1分钟、5分钟、15分钟、30分钟、1小时、4小时、1天 - 支持多种指标：sma、ema、wma、dema、tema、williams、rsi、adx、标准偏差 - 使用from_date和to_date参数进行可选日期范围过滤

1. get_enhanced_dcf_分析：采用场景建模的高级DCF分析

• 输入： {"symbol": "AAPL", "bull_growth_rate": 0.15, "base_growth_rate": 0.10, "bear_growth_rate": 0.05}
• 回报：基于牛市/熊市/熊市情景和投资理论的杠杆DCF计算
• 功能：企业价值计算、财务健康评分、颜色编码建议

1. 获取高级财务健康：综合财务健康评估

• 输入： {"symbol": "AAPL"}
• 回报：Altman Z-Score、Piotroski F-Score和整体财务实力评级
• 特点：破产预测、财务实力评分、趋势分析

发展

本项目使用测试驱动开发（TDD）原则。

设置

git clone https://github.com/cplim/mcp-financial-modeling-server
cd mcp-financial-modeling-server
uv sync --dev

测试

# Run all tests (unit tests only)
uv run pytest

# Run tests with coverage
uv run pytest --cov=src/mcp_financial_modeling_prep --cov-report=term

# Run specific test file
uv run pytest tests/test_financial_tools.py

# Run integration tests (requires FMP_API_KEY)
export FMP_API_KEY="your_api_key_here"
uv run pytest tests/test_fmp_integration.py -m integration

# Run integration tests with script
python scripts/run_integration_tests.py

集成测试

集成测试通过真实的API调用验证FMP API客户端。这些测试：

• 需要FMP_API_KEY：将财务建模准备API键设置为环境变量
• 发出真正的HTTP请求：测试实际API端点和响应
• 验证数据结构：确保API响应符合预期格式
• 测试错误处理：验证API错误和边缘案例的正确处理

获取免费的API密钥:https://financialmodelingprep.com/developer/docs

备注：如果FMP_API_KEY不可用，则在CI/CD中跳过集成测试。

代码质量

在每次提交之前，运行：

uv run black --check .
uv run ruff check .
uv run mypy .

要解决格式问题，请执行以下操作：

uv run ruff check . --fix
uv run black .

项目状态

✅ 完成

• \[x\] 使用uv包管理器进行项目设置
• \[x\] 与GitHub集成的Git存储库
• \[x\] 带有GitHub操作的CI/CD管道
• \[x\] Docker容器化与多拱形构建
• \[x\] GitHub容器注册表（GHCR）集成
• \[x\] TDD框架，具有全面的测试
• \[x\] 支持双传输（stdio+HTTP）的MCP服务器
• \[x\] FMP API客户端实现
• \[x\] 财务数据工具（已实施11个工具）
• \[x\] 市场数据工具（历史价格、指数、交易量）
• \[x\] 财务分析工具（比率、DCF估值、技术指标）
• \[x\] 高级分析工具（增强型DCF，带场景建模，财务健康评分）
• \[x\] 基于JSON的服务模式的模式驱动架构
• \[x\] 可维护架构的服务抽象模式
• \[x\] 错误处理和数据验证
• \[x\] 代码质量检查（黑色、菱形、mypy）
• \[x\] 安全改进（本地主机绑定、漏洞扫描）

🚧 进行中

• \[\]在CI中重新启用80%的代码覆盖率要求

📋 计划的

• \[\]Docker Compose支持多环境部署
• \[\]生产安全增强（原产地验证、身份验证）
• \[\]其他高级分析工具（行业分析、投资组合风险）
• \[\]Kubernetes部署清单

🧪 测试覆盖率

• 总测试：123个单元测试+13个集成测试（全部通过）
• 测试文件：8（服务器、FMP客户端、金融工具、服务、高级服务、模式加载器、传输、集成）
• 覆盖：全面的模拟和集成测试，包括资源和提示
• 建筑：具有单个服务测试的服务抽象模式
• 分析工具：完成财务分析服务的TDD实施，包括高级工具
• 高级功能：通过情景建模增强DCF，通过Altman Z-Score和Piotroski F-Score增强财务健康
• 资源和提示：MCP资源和提示功能的全面测试覆盖
• 配置：基于模式的资源、提示和服务模式加载的测试覆盖率
• 技术指标：增强的API，支持枚举、时间框架和日期范围
• 集成测试：带有FMP端点和错误处理的真实API验证

许可证

MIT许可证