StockMCP

📈 StockMCP

一个功能全面的 Model Context Protocol（MCP）服务，通过 Yahoo Finance 提供实时股市数据

StockMCP 基于 Model Context Protocol 标准，为访问全面的股市数据提供强大的 JSON-RPC 2.0 兼容接口。非常适合 AI 应用、金融分析工具和交易机器人。

🌐 免费托管端点

无需任何设置，即可立即使用 StockMCP！ 我们提供免费的托管端点：

• 端点：https://stockmcp.leoguerin.fr/mcp
• 无需 API 密钥——只需将其添加到 MCP 客户端配置中

Claude Desktop 配置

如需立即访问，请在 claude_desktop_config.json 中使用以下配置：

{
  "mcpServers": {
    "stock-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://stockmcp.leoguerin.fr/mcp",
        "--header",
        "--allow-http"
      ]
    }
  }
}

配置文件位置：

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

🛠️ 可用工具

工具名称	描述
get_realtime_quote	获取当前市场数据，包括价格、成交量、市值和关键财务比率
get_fundamentals	获取全面的财务报表（损益表、资产负债表、现金流量表）和计算得出的比率
get_price_history	获取历史 OHLCV 数据，可选计算包含股息再投资的总回报
get_dividends_and_actions	分析股息支付历史和公司行动，并提供质量指标和一致性评分
get_analyst_forecasts	获取专业分析师的目标价、共识评级（买入/持有/卖出）和 EPS 预测
get_growth_projections	获取营收、收益（EPS）和自由现金流的未来增长预测，包括 1 年、3 年和 5 年 CAGR 估算

🚀 快速开始

设置 API 密钥

1. 获取免费的 Alpha Vantage API 密钥：访问 https://www.alphavantage.co/support/#api-key
2. 配置环境：

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and add your API key
   ALPHAVANTAGE_KEY=your-actual-api-key-here
   

使用 Docker（推荐）

# Clone the repository
git clone https://github.com/yourusername/StockMCP.git
cd StockMCP

# Configure your API key (see API Key Setup above)
cp .env.example .env
# Edit .env with your Alpha Vantage API key

# Build and run with Docker
docker build -t stockmcp .
docker run -p 3001:3001 --env-file .env stockmcp

本地开发

# Install dependencies with uv (fastest)
uv sync

# Or with pip
pip install -e .

# Configure your API key (see API Key Setup above)
cp .env.example .env
# Edit .env with your Alpha Vantage API key

# Run the server
python src/main.py
# Server runs on http://localhost:3001/mcp

MCP 客户端集成

服务启动后，即可将其集成到 MCP 客户端中：

Claude Desktop

编辑配置文件：

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

添加以下配置：

{
  "mcpServers": {
    "stock-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/mcp",
        "--header",
        "--allow-http"
      ]
    }
  }
}

Cursor

添加到 MCP 配置中：

{
  "stock-mcp": {
    "command": "npx",
    "args": [
      "mcp-remote",
      "http://localhost:3001/mcp",
      "--header",
      "--allow-http"
    ]
  }
}

其他 MCP 客户端

对于任何兼容 MCP 的客户端，请使用：

• 端点：http://localhost:3001/mcp
• 协议：通过 HTTP 传输的 JSON-RPC 2.0
• 工具：通过 tools/list 方法获取

🔗 使用方法

StockMCP 实现了 Model Context Protocol（MCP），可与 AI 应用无缝集成。服务启动后，将提供：

• 端点：http://localhost:3001/mcp
• 协议：通过 HTTP 传输的 JSON-RPC 2.0
• 发现：使用 tools/list 获取可用工具
• 执行：使用 tools/call 携带参数执行工具

服务运行时，可访问 http://localhost:3001/mcp/docs 查看交互式文档，了解详细的 API 示例和 JSON 架构。

🛠️ 开发

项目结构

StockMCP/
├── src/
│   ├── main.py              # FastAPI server and endpoints
│   ├── models.py            # Pydantic models for MCP and stock data
│   ├── mcp_handlers.py      # MCP protocol request handlers
│   ├── tools.py             # Tools package entry point
│   └── tools/               # Modular tools implementation
│       ├── market_data.py   # Real-time quotes, history, fundamentals
│       ├── analysis.py      # Forecasts and growth projections
│       └── registry.py      # Tool registration and execution
├── tests/                   # Comprehensive test suite (100 tests)
├── Dockerfile              # Container configuration
├── pyproject.toml          # Project dependencies and configuration
└── README.md              # This file

运行测试

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

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

# Run with coverage
uv run pytest --cov=src

依赖项

核心依赖项：

• FastAPI - 用于构建 API 的现代 Web 框架
• Pydantic - 使用 Python 类型提示进行数据验证
• yfinance - 获取 Yahoo Finance 数据（主要数据源）
• pandas - 数据处理与分析
• scipy - 科学计算（yfinance 所需）

开发依赖项：

• pytest - 测试框架
• httpx - 用于测试的 HTTP 客户端
• pytest-mock - 模拟工具

🐳 Docker 部署

构建并运行

# Build the image
docker build -t stockmcp .

# Run the container
docker run -p 3001:3001 stockmcp

# Run in background
docker run -d -p 3001:3001 --name stockmcp-server stockmcp

环境配置

容器默认在端口 3001 上公开 API。你可以自定义此设置：

# Custom port mapping
docker run -p 8080:3001 stockmcp

# With environment variables
docker run -p 3001:3001 -e LOG_LEVEL=DEBUG stockmcp

🔧 配置

服务配置

可以通过环境变量配置服务：

• LOG_LEVEL - 日志级别（DEBUG、INFO、WARNING、ERROR）
• HOST - 服务主机（默认值：0.0.0.0）
• PORT - 服务端口（默认值：3001）

API 限制与数据源

主要数据源：Yahoo Finance（yfinance）

• 免费套餐，速率限制较为宽松
• 实时和历史数据
• 基本用法无需 API 密钥

次要数据源：Alpha Vantage（可选）

• 提供更丰富的收益预估和预测
• 使用扩展功能需要免费 API 密钥
• 服务不可用时会平稳回退

生产环境建议：

• 实现请求缓存
• 添加带指数退避的重试逻辑
• 监控 API 使用模式
• 考虑数据源冗余

🤝 参与贡献

欢迎贡献！以下是开始参与的方法：

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改并编写适当的测试
4. 运行测试套件（uv run pytest）
5. 提交更改（git commit -m 'Add amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 创建 Pull Request

开发指南

• 类型提示 - 所有函数都应包含适当的类型注解
• 测试 - 新功能必须包含全面的测试
• 文档 - API 有任何更改时，请更新 README 和文档字符串
• 代码风格 - 遵循 PEP 8，并使用有意义的变量名

📝 许可证

本项目基于 MIT License 授权 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Yahoo Finance - 提供免费的股票市场数据
• Model Context Protocol - 提供优秀的协议规范
• FastAPI - 提供出色的 Web 框架
• Pydantic - 提供可靠的数据验证

📞 支持

• 🐛 错误报告 - 提交问题
• 💡 功能请求 - 发起讨论
• 📖 文档 - 查阅我们全面的 API 文档
• 💬 社区 - 加入讨论，获取帮助并交流想法

---