Back to Directory/AI & ML

ai.smithery/xinkuang-china-stock-mcp

Access real-time and historical market data for China A-shares and Hong Kong stocks, along with ne…

AI & MLPythonv1.15.0
View on GitHub

china-stock-mcp

smithery badge 一款股票 MCP (Model Context Protocol) 服务器，为中国股市数据提供接口。提供了一系列工具，用于获取财务信息，包括历史股票数据、实时数据、新闻数据、财务报表等。

🚀 核心特性

  • 双模式运行: 支持 stdio 本地模式和 HTTP 网络模式
  • 丰富的财务数据: 涵盖 A/B/H 股数据的全方位获取
  • 实时数据: 支持实时股价、交易信息等
  • 财务报表: 资产负债表、利润表、现金流量表等
  • 技术指标: 30+ 种技术指标自动计算和添加
  • 新闻数据: 股票相关新闻和公告信息
  • 易用性: 简单配置即可集成到 AI 助手 (Claude、Cursor 等)
  • 数据缓存: 内置内存和磁盘缓存机制，提高数据获取效率和响应速度
  • 容器化: 支持 Docker 部署

🛠️ 架构概览

主要组件

  • server.py: MCP 服务器核心，定义所有工具和数据接口
  • __main__.py: 命令行入口，支持多种运行模式
  • FastMCP 框架: 处理 MCP 协议通信
  • akshare-one 库: 提供底层的中国股市数据获取能力
  • cache_utils.py: 缓存工具，提供内存和磁盘缓存功能

支持的数据源

  • **数据源故障切换**: 内置 `_fetch_data_with_fallback` 机制，支持按优先级自动切换数据源。当首选数据源失败或返回空数据时，系统将自动尝试备用数据源，从而提高数据获取的稳定性和可靠性。

  • 东方财富 (eastmoney, eastmoney_direct)

  • 新浪财经 (sina)

  • 雪球 (xueqiu)

📋 可用工具

1. 获取股票的历史行情数据，支持多种数据源和技术指标 (get_hist_data)

获取股票历史行情数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • interval (Literal): 时间周期: minute, hour, day, week, month, year。默认:day
  • interval_multiplier (int): 时间周期乘数
  • start_date (string): 开始日期，格式为 YYYY-MM-DD
  • end_date (string): 结束日期，格式为 YYYY-MM-DD
  • adjust (Literal): 复权类型: none, qfq(前复权), hfq(后复权)。默认：none
  • `indicators_list` (string|list): 要添加的技术指标，可以是逗号分隔的字符串（例如: 'SMA,EMA'）或字符串列表（例如: ['SMA', 'EMA']）。支持的指标包括: SMA, EMA, RSI, MACD, BOLL, STOCH, ATR, CCI, ADX, WILLR, AD, ADOSC, OBV, MOM, SAR, TSF, APO, AROON, AROONOSC, BOP, CMO, DX, MFI, MINUS_DI, MINUS_DM, PLUS_DI, PLUS_DM, PPO, ROC, ROCP, ROCR, ROCR100, TRIX, ULTOSC。常用指标：SMA, EMA, RSI, MACD, BOLL, STOCH, OBV, MFI,建议不超过10个。
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

2. 获取股票的实时行情数据，支持多种数据源 (get_realtime_data)

获取实时股票行情数据，支持的数据源包括：eastmoney, eastmoney_direct, xueqiu。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

3. 获取股票相关的新闻数据 (get_news_data)

获取股票相关新闻数据.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

4. 获取公司的资产负债表数据 (get_balance_sheet)

获取公司资产负债表数据.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

5. 获取指定股票代码的公司的利润表数据 (get_income_statement)

获取公司利润表数据.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

6. 获取指定股票代码的公司的现金流量表数据 (get_cash_flow)

获取公司现金流量表数据.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

7. 获取股票的近 100 个交易日的资金流向数据 (get_fund_flow)

获取股票的近 100 个交易日的资金流向数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

8. 获取公司的内部股东交易数据 (get_inner_trade_data)

获取公司内部股东交易数据.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

9. 获取三大财务报表的关键财务指标 (get_financial_metrics)

获取三大财务报表的关键财务指标.

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

10. 获取当前时间（ISO格式、时间戳）和最近一个交易日 (get_time_info)

获取当前时间（ISO格式、时间戳）和最近一个交易日.

参数: 无

11. 获取指定股票的基本概要信息 (get_stock_basic_info)

获取股票基本概要信息，支持 A 股和港股

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

12. 获取单个宏观经济指标数据 (get_macro_data)

获取单个宏观经济指标数据

参数:

  • indicator (Literal): 要获取的宏观经济指标。支持的指标包括: money_supply, gdp, cpi, pmi, stock_summary。默认: 'gdp'
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

13. 分析散户和机构投资者的投资情绪 (get_investor_sentiment)

分析散户和机构投资者的投资情绪

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

14. 获取指定股票的股东情况 (get_shareholder_info)

获取股东情况

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

15. 获取指定股票公司的主要产品或业务构成 (get_product_info)

获取产品情况

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

16. 获取股票的业绩预测数据，包括预测年报净利润和每股收益 (get_profit_forecast)

获取股票的业绩预测数据。

参数:

  • symbol (string): 股票代码 (例如: '600519')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

17. 获取分红送股详情 (get_stock_fhps_detail)

获取指定股票的分红送股详情数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

18. 获取筹码分布数据 (get_stock_cyq)

获取指定股票的筹码分布数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • date (string): 查询日期，格式为 YYYY-MM-DD
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

19. 获取股票研究报告 (get_stock_research_report)

获取指定股票的研究报告数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

20. 获取流通股东数据 (get_stock_circulate_stock_holder)

获取指定股票的流通股东数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

21. 获取高管变动数据 (get_stock_management_change)

获取指定股票的高管变动数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

22. 获取限售解禁数据 (get_stock_restricted_release_queue)

获取指定股票的限售解禁数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

23. 获取 A 股代码和名称 (get_stock_a_code_name)

获取所有 A 股股票的代码和名称。

参数:

  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

24. 获取股票估值数据 (get_stock_value)

获取指定股票的估值数据。

参数:

  • symbol (string): 股票代码 (例如: '000001')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

25. 计算指定个股的波动率指标 (get_stock_volatility)

通过分钟级历史行情计算指定个股的波动率指标。 参数:

  • symbol (string): 股票代码 (例如: '000001')
  • start_date(string): 开始日期
  • end_date(string): 结束日期
  • period (int): 时间周期，分钟级别 (例如: '1', '5', '15', '30', '60')")
  • adjust(string): 复权类型: none, qfq(前复权), hfq(后复权)。默认：none
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

26. 获取所有指数的代码和基本信息 (get_all_cni_indices)

获取所有指数的代码和基本信息，去除实时变动数据并支持缓存。

参数:

  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

27. 获取指定指数的日频率历史行情数据 (get_cni_index_hist)

获取指定指数的日频率历史行情数据。

参数:

  • symbol (string): 指数代码 (例如: '399005')
  • start_date (string): 开始日期，格式为 YYYYMMDD (例如: '20230114')
  • end_date (string): 结束日期，格式为 YYYYMMDD (例如: '20240114')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

28. 获取指定指数的成分股样本详情 (get_cni_index_detail)

获取指定指数的成分股样本详情。

参数:

  • symbol (string): 指数代码 (例如: '399001')
  • date (string): 日期，格式为 YYYYMM (例如: '202404')
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

29. 获取技术选股指标数据，包括创新高、创新低、连续上涨、连续下跌、持续放量、持续缩量、向上突破、向下突破、量价齐升、量价齐跌、险资举牌。(get_stock_technical_rank)

参数:

  • indicator_name (string): 要获取的技术指标名称 (例如: 创新高-创月新高, 创新高-半年新高, 创新高-一年新高, 创新高-历史新高, 创新低-创月新低, 创新低-半年新低, 创新低-一年新低, 创新低-历史新低, 连续上涨, 连续下跌, 持续放量, 持续缩量, 向上突破-5日均线, 向上突破-10日均线, 向上突破-20日均线, 向上突破-30日均线, 向上突破-60日均线, 向上突破-90日均线, 向上突破-250日均线, 向上突破-500日均线, 向下突破-5日均线, 向下突破-10日均线, 向下突破-20日均线, 向下突破-30日均线, 向下突破-60日均线, 向下突破-90日均线, 向下突破-250日均线, 向下突破-500日均线, 量价齐升, 量价齐跌, 险资举牌)
  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

30. 获取所有行业板块实时行情数据 (get_stock_board_industry_summary)

参数:

  • output_format (Literal): 输出数据格式: json, csv, xml, excel, markdown, html。默认:markdown

🚀 安装和运行

方法一: 使用 Smithery

通过 Smithery 自动安装到 Claude Desktop：

bash
npx -y @smithery/cli install @xinkuang/china-stock-mcp

方法二: 使用 Docker

1. 拉取镜像

bash
docker pull ghcr.io/xinkuang/china-stock-mcp:latest

2. 运行容器

bash
docker run -p 8081:8081 ghcr.io/xinkuang/china-stock-mcp:latest

方法三: 本地源代码安装

1. 环境要求

  • Python 3.12+
  • Git
  • uv (推荐的 Python 包管理器)

2. 克隆仓库

bash
git clone https://github.com/xinkuang/china-stock-mcp
cd china-stock-mcp

3. 安装依赖

bash
# 推荐使用 uv 包管理器
uv sync

# 或者使用 pip
pip install -r requirements.txt

4. 运行服务器

stdio 模式 (默认，适用于本地 MCP 客户端):

bash
uv run -m china_stock_mcp

HTTP 模式 (适用于远程访问):

bash
uv run -m china_stock_mcp --streamable-http --host 0.0.0.0 --port 8081

服务器将在 http://localhost:8081/mcp 提供服务。

⚙️ MCP 配置示例

Claude Desktop 配置

编辑 claude_desktop_config.json：

方式一: 本地源代码

json
{
  "mcpServers": {
    "china-stock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/china_stock_mcp",
        "run",
        "china-stock-mcp"
      ]
    }
  }
}

方式二: 通过 uvx

json
{
    "mcpServers": {
        "china-stock-mcp": {
            "command": "uvx",
            "args": [
              "china-stock-mcp"
            ]
        }
    }
}

方式三: HTTP 模式

json
{
  "mcpServers": {
    "china-stock-mcp": {
      "command": "uvx",
      "args": ["china-stock-mcp", "--streamable-http", "--host", "0.0.0.0", "--port", "8081"],
      "env": {
        "MCP_BASE_URL": "http://localhost:8081/mcp"
      }
    }
  }
}

其他 AI 客户端配置

Cursor:

json
{
  "mcpServers": {
    "china-stock-mcp": {
      "command": "uvx",
      "args": [ "china-stock-mcp"]
    }
  }
}

Clion with MCP:

json
{
  "mcpServers": {
    "china-stock-mcp": {
      "command": "uvx",
    "args": [ "china-stock-mcp"]
    }
  }
}

🏃‍♂️ 命令行参数

  • --streamable-http: 启用 HTTP 可流式模式 (默认: stdio 模式)
  • --host: HTTP 模式下的绑定主机 (默认: 0.0.0.0)
  • --port: HTTP 模式下的监听端口 (默认: 8081)

📊 数据支持范围

股票市场

  • A股 (上证、深证)
  • B股
  • H股 (港股)
  • 中小板、创业板、新三板

数据类型

  • 历史行情数据 (分钟级、小时级、日级、周级、月级、年级)
  • 实时行情数据
  • 技术指标计算
  • 新闻资讯
  • 财务报表 (资产负债表、利润表、现金流量表)
  • 财务指标
  • 内部交易数据

🔧 开发和贡献

开发环境设置

  1. 克隆仓库
bash
git clone https://github.com/xinkuang/china-stock-mcp
cd china-stock-mcp
  1. 安装开发依赖
bash
uv sync --dev
  1. 进入开发模式
bash
uv run -m china_stock_mcp

代码结构

text
src/china_stock_mcp/
├── __init__.py
├── __main__.py    # 命令行入口，处理启动参数
├── server.py      # MCP 服务器核心，定义所有工具
├── mcp.json       # MCP 配置规范 (可选)
└── py.typed       # 类型标注文件

添加新工具

在 server.py 中使用 @mcp.tool 装饰器添加新工具：

python
@mcp.tool(name="工具中文名称", description="工具的中文描述")
def your_tool_name(param1: Annotated[str, Field(description="参数描述")]) -> str:
    """工具详情描述"""
    # 实现逻辑
    pass

📝 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🙋‍♂️ 常见问题

Q: 为什么无法获取数据？ A: 请检查网络连接和数据源可用性。某些数据源可能有访问限制。

Q: HTTP 模式下无法连接？ A: 确认端口 8081 未被其他服务占用，且防火墙允许相应端口的访问。

Q: 如何更新到最新版本？ A: 使用 Smithery 安装的可以自动更新，手动安装的请重新拉取仓库代码。

🐞 调试

有关如何使用 @modelcontextprotocol/inspector 调试此服务器的详细信息，请参阅 DEBUG.md。

Learn More

How to Use MCP Servers With Ollama and Local LLMsOllama does not natively speak MCP, but bridge tools like MCPHost let local models call MCP tools over stdio. MCPFind indexes 832 servers in the ai-ml category. This guide covers which models support tool calling, how to wire MCPHost to any local model, and which server categories are worth running offline.Read articleMCP vs LangChain Tools: Which Should You Use?LangChain tools and MCP servers both give AI models access to external functions, but they work at different layers. This guide compares them on architecture, cross-client reuse, and long-term maintenance using adoption data from the MCPFind directory's 6,105 indexed servers.Read articleMCP vs Function Calling: Which Should You Build With?MCP and function calling solve different problems in AI agent architecture. Function calling is tight, in-process, and fast. MCP is modular, reusable across models, and designed for production tooling. We analyzed both patterns against real servers in the MCPFind directory to map out when each one wins.Read article