China Stock MCP

🚀 china-stock-mcp

china-stock-mcp 是一款基於 akshare-one 構建的 MCP (Model Context Protocol) 服務器，為中國股市數據提供接口。它提供了一系列工具，可用於獲取財務信息，包括歷史股票數據、即時數據、新聞數據、財務報表等。

🚀 快速開始

安裝和運行

方法一: 使用 Smithery

通過 Smithery 自動安裝到 Claude Desktop：

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

方法二: 使用 Docker

1. 拉取鏡像

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

2. 運行容器

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

方法三: 本地源代碼安裝

1. 環境要求
   • Python 3.12+
   • Git
   • uv (推薦的 Python 包管理器)
2. 克隆倉庫

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

3. 安裝依賴

# 推薦使用 uv 包管理器
uv sync

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

4. 運行服務器
   • stdio 模式 (默認，適用於本地 MCP 客戶端):

uv run -m china_stock_mcp

- **HTTP 模式 (適用於遠程訪問):**

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：

• 方式一: 本地源代碼

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

• 方式二: 通過 uvx

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

• 方式三: HTTP 模式

{
  "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:

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

• Clion with MCP:

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

✨ 主要特性

• 雙模式運行：支持 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)

命令行參數

• --streamable-http：啟用 HTTP 可流式模式 (默認: stdio 模式)。
• --host：HTTP 模式下的綁定主機 (默認: 0.0.0.0)。
• --port：HTTP 模式下的監聽端口 (默認: 8081)。

數據支持範圍

股票市場

• A股 (上證、深證)
• B股
• H股 (港股)
• 中小板、創業板、新三板

數據類型

• 歷史行情數據 (分鐘級、小時級、日級、周級、月級、年級)
• 即時行情數據
• 技術指標計算
• 新聞資訊
• 財務報表 (資產負債表、利潤表、現金流量表)
• 財務指標
• 內部交易數據

開發和貢獻

開發環境設置

1. 克隆倉庫

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

2. 安裝開發依賴

uv sync --dev

3. 進入開發模式

uv run -m china_stock_mcp

代碼結構

src/china_stock_mcp/
├── __init__.py
├── __main__.py    # 命令行入口，處理啟動參數
├── server.py      # MCP 服務器核心，定義所有工具
├── mcp.json       # MCP 配置規範 (可選)
└── py.typed       # 類型標註文件

添加新工具

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

@mcp.tool(name="工具中文名稱", description="工具的中文描述")
def your_tool_name(param1: Annotated[str, Field(description="參數描述")]) -> str:
    """工具詳情描述"""
    # 實現邏輯
    pass

📦 可用工具

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

📄 許可證

MIT License - 詳見 LICENSE 文件。

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

🙋‍♂️ 常見問題

Q: 為什麼無法獲取數據？ A: 請檢查網絡連接和數據源可用性。某些數據源可能有訪問限制。

Q: HTTP 模式下無法連接？ A: 確認端口 8081 未被其他服務佔用，且防火牆允許相應端口的訪問。

Q: 如何更新到最新版本？ A: 使用 Smithery 安裝的可以自動更新，手動安裝的請重新拉取倉庫代碼。

🐞 調試

有關如何使用 @modelcontextprotocol/inspector 調試此服務器的詳細信息，請參閱 DEBUG.md。