本项目旨在为 AI Agent（如 Claude, Cursor, 通义千问等）赋予专业级的股市分析能力，打通大语言模型与实时金融数据之间的桥梁。

通过 MCP (Model Context Protocol) 协议，AI 可以直接调用本服务器提供的金融工具，实现：

• 📊 实时行情查询
• 📈 技术指标计算
• 💰 基本面分析
• 📰 新闻资讯获取
• 🔍 深度研究报告

无需纠结使用哪个 API。本服务器内置智能 Adapter Manager（适配器管理器），可自动路由请求并在多个数据源之间进行故障转移：

• 美股: Yahoo Finance, Finnhub
• A股: Akshare, Tushare, Baostock
• 加密货币: CCXT (Binance, OKX 等)
• 外汇与指数: Yahoo Finance

内置量化分析引擎，提供的不仅仅是原始数字：

• 技术指标: SMA/EMA, RSI, MACD, 布林带 (Bollinger Bands), KDJ, ATR 等
• 形态识别: 自动检测 K 线形态（如十字星 Doji, 锤头线 Hammer, 吞没形态 Engulfing）
• 支撑与压力: 动态计算关键价格位
• 筹码分布 (Volume Profile): 分析成交量分布以识别价值区域

自动化的金融分析师能力：

• 财务报表: 资产负债表、利润表、现金流量表
• 健康度打分: 基于盈利能力、偿债能力、成长性和估值的 0-100 分独家健康度评分
• 关键比率: PE, PB, ROE, ROA, 负债权益比等

专为 LLM 上下文窗口优化：

• perform_deep_research: 一键获取指定标的的 价格 + 历史走势 + 基本面 + 近期新闻
• get_market_report: 获取当前市场状态的综合快照

• Python 3.10+
• Redis (可选，用于缓存)

1. 克隆仓库

   git clone https://github.com/yourusername/stock-tool-mcp.git
   cd stock-tool-mcp

2. 创建并激活 Conda 环境

   # 创建 Python 3.11.14 环境
   conda create -n stock-mcp python=3.11.14
   
   # 激活环境
   conda activate stock-mcp

3. 安装依赖

   pip install -r requirements.txt

4. 配置环境变量

   复制示例环境变量文件:

   cp .env.example .env

   编辑 .env 添加你的 API 密钥（可选，但推荐以获得更高限额）:

   • TUSHARE_TOKEN - 用于 A 股数据（获取 Token）
   • FINNHUB_API_KEY - 用于美股机构数据（获取 API Key）
   • DASHSCOPE_API_KEY - 用于阿里百炼 AI（可选，用于测试）

使用 uvicorn 启动 MCP 服务器（Streamable HTTP 模式）：

# 设置环境变量指定传输方式为 streamable-http
export MCP_TRANSPORT=streamable-http

# 标准启动（监听 9898 端口）
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# 开发模式（支持热重载）
MCP_TRANSPORT=streamable-http python -m uvicorn src.server.app:app --reload --port 9898

启动成功后，你会看到：

✅ MCP server ready!

使用示例（Streamable HTTP）：

stdio 模式通过标准输入输出与 AI Agent 通信，适合 Claude Desktop、Cursor 等本地集成。

快速启动：

# 使用启动脚本（已配置好 conda 环境）
bash start_stock_mcp_stdio.sh

手动启动：

# 激活 conda 环境
conda activate stock-mcp

# 启动 stdio 模式（默认传输方式）
python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"

集成到 Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stock-tools": {
      "command": "bash",
      "args": ["start_stock_mcp_stdio.sh"],
      "cwd": "/path/to/stock-tool-mcp"
    }
  }
}

集成到 Cursor (.cursor/mcp_config.json):

{
  "mcpServers": {
    "stock-tools": {
      "command": "bash",
      "args": ["start_stock_mcp_stdio.sh"],
      "cwd": "/path/to/stock-tool-mcp"
    }
  }
}

使用示例（stdio 模式）：

服务器启动后，可以通过 HTTP 接口调用（Streamable HTTP 协议）：

# 列出所有可用工具
curl -X POST http://localhost:9898 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": "1"
  }'

# 调用工具示例：查询贵州茅台价格
curl -X POST "http://localhost:9898/?_tool=get_real_time_price" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_real_time_price",
      "arguments": {
        "ticker": "SSE:600519"
      }
    },
    "id": "2"
  }'

💡 重要提示:

• A股股票代码格式：SSE:600519（上交所）、SZSE:000001（深交所）
• 美股股票代码格式：NASDAQ:AAPL、NYSE:TSLA
• 加密货币格式：CRYPTO:BTC、CRYPTO:ETH

本项目支持两种传输协议，分别适用于不同场景：

适合通过 HTTP 接口调用，方便测试和集成到 Web 应用：

适合直接集成到 AI Agent（如 Claude Desktop、Cursor），通过标准输入输出通信：

💡 两种模式的区别：

• Streamable HTTP: 需要启动 Web 服务器，支持远程调用，适合生产环境
• stdio: 直接进程通信，无需网络端口，适合本地 AI Agent 集成，延迟更低

项目提供了完整的测试脚本，帮助你快速验证功能：

使用 scripts/test_mcp_http.py 测试 MCP 服务器的 HTTP 接口：

# 1. 启动 MCP 服务器（在一个终端）
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# 2. 在另一个终端运行测试脚本
python scripts/test_mcp_http.py

该脚本会：

• ✅ 连接到 MCP 服务器（http://localhost:9898）
• ✅ 列出所有可用工具
• ✅ 使用阿里百炼（通义千问）调用工具
• ✅ 查询贵州茅台的价格和基本面

使用 scripts/mcp2openapi.py 生成 OpenAPI 规范文档：

python scripts/mcp2openapi.py

生成的 OpenAPI 文档可以导入到 Apifox、Postman 等工具中进行测试。

虽然当前的数据检索和分析能力已相当健壮，但以下功能计划在未来版本中支持：

• 实盘交易执行: 目前 execute_order 工具处于 模拟模式 (Simulation Mode)。我们计划通过 CCXT（加密货币）和券商 API（股票）集成真实的交易下单能力
• 高级缓存策略: 实现更细粒度的 TTL (Time-To-Live) 设置，区分实时价格数据（短 TTL）和财务报表（长 TTL），以平衡性能与 API 配额消耗
• 用户账户管理: 安全地管理用户特定的交易所 API 密钥，实现个性化交易
• 更多数据适配器: 扩展支持更多专业数据源（如情绪分析提供商、另类数据等）
• WebSocket 实时推送: 支持实时行情推送，减少轮询开销
• 回测引擎: 内置策略回测功能，验证交易策略的有效性

本项目采用 领域驱动设计 (DDD) 架构，清晰分离关注点：

src/server/
├── app.py                 # FastMCP 应用入口
├── config/                # 配置管理
├── core/                  # 核心业务逻辑
│   └── dependencies.py    # 依赖注入容器
├── domain/                # 领域层
│   ├── adapters/          # 数据适配器（Yahoo, Akshare, Tushare 等）
│   ├── models/            # 领域模型
│   └── services/          # 领域服务
├── infrastructure/        # 基础设施层
│   ├── cache/             # 缓存（Redis）
│   └── external/          # 外部 API 客户端
├── mcp/                   # MCP 协议层
│   └── tools/             # MCP 工具定义
└── utils/                 # 工具类

核心设计原则:

• 📦 适配器模式: 统一多数据源接口，自动故障转移
• 🔌 依赖注入: 使用 dependency-injector 管理服务生命周期
• ⚡ 异步优先: 所有外部调用均为异步，提升并发性能
• 🎯 单一职责: 每个服务专注于特定领域功能

MIT License

A powerful, comprehensive Model Context Protocol (MCP) server for financial market data, technical analysis, and fundamental research.

Designed to empower AI agents (like Claude, Cursor, etc.) with professional-grade stock market capabilities, bridging the gap between LLMs and real-time financial data.

Stop worrying about which API to use. The server features a smart Adapter Manager that automatically routes requests and handles failover across multiple providers:

• US Stocks: Yahoo Finance, Finnhub
• China A-Shares: Akshare, Tushare, Baostock
• Crypto: CCXT (Binance, OKX, etc.)
• Forex & Indices: Yahoo Finance

Built-in quantitative analysis engine providing more than just raw numbers:

• Indicators: SMA/EMA, RSI, MACD, Bollinger Bands, KDJ, ATR
• Pattern Recognition: Automatically detects candlestick patterns (Doji, Hammer, Engulfing)
• Support & Resistance: Dynamic calculation of key price levels
• Volume Profile: Analysis of volume distribution to identify value areas

Automated financial analyst capabilities:

• Financial Statements: Balance Sheet, Income Statement, Cash Flow
• Health Scoring: 0-100 proprietary health score based on Profitability, Solvency, Growth, and Valuation
• Key Ratios: PE, PB, ROE, ROA, Debt-to-Equity, and more

Optimized for LLM context windows:

• perform_deep_research: One-shot tool to fetch price, history, fundamentals, and recent news for a symbol
• get_market_report: A comprehensive snapshot of the current market status

• Python 3.10+
• Redis (optional, for caching)

1. Clone the repository

   git clone https://github.com/yourusername/stock-tool-mcp.git
   cd stock-tool-mcp

2. Create and activate Conda environment

   # Create Python 3.11.14 environment
   conda create -n stock-mcp python=3.11.14
   
   # Activate environment
   conda activate stock-mcp

3. Install dependencies

   pip install -r requirements.txt

4. Configuration

   Copy the example environment file:

   cp .env.example .env

   Edit .env to add your API keys (optional but recommended for higher limits):

   • TUSHARE_TOKEN - For China A-shares data (Get Token)
   • FINNHUB_API_KEY - For US institutional data (Get API Key)
   • DASHSCOPE_API_KEY - For Alibaba Cloud AI (optional, for testing)

Start the MCP server using uvicorn (Streamable HTTP mode):

# Set environment variable to specify transport mode
export MCP_TRANSPORT=streamable-http

# Standard run (listening on port 9898)
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# Development mode (with hot reload)
MCP_TRANSPORT=streamable-http python -m uvicorn src.server.app:app --reload --port 9898

After successful startup, you'll see:

✅ MCP server ready!

Example (Streamable HTTP mode):

stdio mode communicates with AI agents via standard input/output, suitable for local integration with Claude Desktop, Cursor, etc.

Quick Start:

# Use the startup script (conda environment pre-configured)
bash start_stock_mcp_stdio.sh

Manual Start:

# Activate conda environment
conda activate stock-mcp

# Start stdio mode (default transport)
python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"

Integrate with Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stock-tools": {
      "command": "bash",
      "args": ["start_stock_mcp_stdio.sh"],
      "cwd": "/path/to/stock-tool-mcp"
    }
  }
}

Integrate with Cursor (.cursor/mcp_config.json):

{
  "mcpServers": {
    "stock-tools": {
      "command": "bash",
      "args": ["start_stock_mcp_stdio.sh"],
      "cwd": "/path/to/stock-tool-mcp"
    }
  }
}

Example (stdio mode):

After starting the server, you can call it via HTTP interface (Streamable HTTP protocol):

# List all available tools
curl -X POST http://localhost:9898 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": "1"
  }'

# Call tool example: Query Moutai stock price
curl -X POST "http://localhost:9898/?_tool=get_real_time_price" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_real_time_price",
      "arguments": {
        "ticker": "SSE:600519"
      }
    },
    "id": "2"
  }'

💡 Important Note:

• A-share ticker format: SSE:600519 (Shanghai), SZSE:000001 (Shenzhen)
• US stock ticker format: NASDAQ:AAPL, NYSE:TSLA
• Crypto format: CRYPTO:BTC, CRYPTO:ETH

This project supports two transport protocols, each suitable for different scenarios:

Suitable for HTTP interface calls, convenient for testing and integration into web applications:

Suitable for direct integration into AI Agents (like Claude Desktop, Cursor), communicating via standard input/output:

💡 Differences Between the Two Modes:

• Streamable HTTP: Requires a web server, supports remote calls, suitable for production environments
• stdio: Direct process communication, no network port required, suitable for local AI Agent integration with lower latency

The project provides comprehensive test scripts to help you quickly verify functionality:

Use scripts/test_mcp_http.py to test the MCP server's HTTP interface:

# 1. Start the MCP server (in one terminal)
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# 2. Run the test script in another terminal
python scripts/test_mcp_http.py

This script will:

• ✅ Connect to the MCP server (http://localhost:9898)
• ✅ List all available tools
• ✅ Use Alibaba Cloud Qwen to call tools
• ✅ Query Moutai's price and fundamentals

Use scripts/mcp2openapi.py to generate OpenAPI specification:

python scripts/mcp2openapi.py

The generated OpenAPI documentation can be imported into tools like Apifox or Postman for testing.

While the data retrieval and analysis capabilities are robust, the following features are planned for future releases:

• Real Trading Execution: Currently, the execute_order tool runs in simulation mode. We plan to integrate real trading capabilities via CCXT (for crypto) and broker APIs (for stocks)
• Advanced Caching Strategy: Implement fine-grained TTL (Time-To-Live) settings to distinguish between real-time price data (short TTL) and financial reports (long TTL) for better performance and API quota management
• User Account Management: Secure handling of user-specific exchange API keys for personalized trading
• More Data Adapters: Expansion to include more specialized data sources (e.g., sentiment analysis providers, alternative data)
• WebSocket Real-time Push: Support real-time market data push to reduce polling overhead
• Backtesting Engine: Built-in strategy backtesting functionality to validate trading strategies

This project adopts Domain-Driven Design (DDD) architecture with clear separation of concerns:

src/server/
├── app.py                 # FastMCP application entry
├── config/                # Configuration management
├── core/                  # Core business logic
│   └── dependencies.py    # Dependency injection container
├── domain/                # Domain layer
│   ├── adapters/          # Data adapters (Yahoo, Akshare, Tushare, etc.)
│   ├── models/            # Domain models
│   └── services/          # Domain services
├── infrastructure/        # Infrastructure layer
│   ├── cache/             # Caching (Redis)
│   └── external/          # External API clients
├── mcp/                   # MCP protocol layer
│   └── tools/             # MCP tool definitions
└── utils/                 # Utilities

Core Design Principles:

• 📦 Adapter Pattern: Unified multi-source interface with automatic failover
• 🔌 Dependency Injection: Using dependency-injector for service lifecycle management
• ⚡ Async First: All external calls are asynchronous for improved concurrency
• 🎯 Single Responsibility: Each service focuses on specific domain functionality

MIT License