China Stock MCP

🚀 china-stock-mcp

A MCP (Model Context Protocol) server built on akshare-one, providing interfaces for Chinese stock market data. It offers a series of tools for obtaining financial information, including historical stock data, real-time data, news data, financial statements, etc.

✨ Features

• Dual-mode operation: Supports both stdio local mode and HTTP network mode.
• Rich financial data: Covers comprehensive data acquisition for A/B/H shares.
• Real-time data: Supports real-time stock prices, trading information, etc.
• Financial statements: Balance sheets, income statements, cash flow statements, etc.
• Technical indicators: Automatically calculates and adds over 30 technical indicators.
• News data: Stock-related news and announcements.
• Ease of use: Can be easily integrated into AI assistants (Claude, Cursor, etc.) with simple configuration.
• Data caching: Built-in memory and disk caching mechanisms to improve data acquisition efficiency and response speed.
• Containerization: Supports Docker deployment.

🔧 Technical Details

Main Components

• server.py: The core of the MCP server, defining all tools and data interfaces.
• __main__.py: The command-line entry, supporting multiple operating modes.
• FastMCP framework: Handles MCP protocol communication.
• akshare-one library: Provides the underlying ability to obtain Chinese stock market data.
• cache_utils.py: A caching tool that offers memory and disk caching functions.

Supported Data Sources

• Data source failover: The built-in _fetch_data_with_fallback mechanism supports automatic switching of data sources by priority. When the preferred data source fails or returns empty data, the system will automatically attempt the backup data source, thereby improving the stability and reliability of data acquisition.
• Eastmoney (eastmoney, eastmoney_direct)
• Sina Finance (sina)
• Xueqiu (xueqiu)

📋 Available Tools

1. Get historical market data of stocks, supporting multiple data sources and technical indicators (get_hist_data)

Get historical market data of stocks.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• interval (Literal): Time interval: minute, hour, day, week, month, year. Default: 'day'.
• interval_multiplier (int): Time interval multiplier.
• start_date (string): Start date in the format of YYYY-MM-DD.
• end_date (string): End date in the format of YYYY-MM-DD.
• adjust (Literal): Restoration type: none, qfq (front restoration), hfq (back restoration). Default: 'none'.
• indicators_list (string|list): Technical indicators to be added, which can be a comma-separated string (e.g., 'SMA,EMA') or a list of strings (e.g., ['SMA', 'EMA']). Supported indicators include: 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. Commonly used indicators are SMA, EMA, RSI, MACD, BOLL, STOCH, OBV, MFI. It is recommended not to exceed 10.
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

2. Get real-time market data of stocks, supporting multiple data sources (get_realtime_data)

Get real-time market data of stocks. Supported data sources include: eastmoney, eastmoney_direct, xueqiu.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

3. Get news data related to stocks (get_news_data)

Get news data related to stocks.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

4. Get the balance sheet data of a company (get_balance_sheet)

Get the balance sheet data of a company.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

5. Get the income statement data of a company with the specified stock code (get_income_statement)

Get the income statement data of a company.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

6. Get the cash flow statement data of a company with the specified stock code (get_cash_flow)

Get the cash flow statement data of a company.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

7. Get the fund flow data of a stock in the past 100 trading days (get_fund_flow)

Get the fund flow data of a stock in the past 100 trading days.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

8. Get the insider trading data of a company (get_inner_trade_data)

Get the insider trading data of a company.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

9. Get the key financial indicators of the three major financial statements (get_financial_metrics)

Get the key financial indicators of the three major financial statements.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

10. Get the current time (ISO format, timestamp) and the most recent trading day (get_time_info)

Get the current time (ISO format, timestamp) and the most recent trading day.

Parameters: None

11. Get the basic summary information of a specified stock (get_stock_basic_info)

Get the basic summary information of a stock, supporting A-shares and Hong Kong stocks.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

12. Get the data of a single macroeconomic indicator (get_macro_data)

Get the data of a single macroeconomic indicator.

Parameters:

• indicator (Literal): Macroeconomic indicator to be obtained. Supported indicators include: money_supply, gdp, cpi, pmi, stock_summary. Default: 'gdp'.
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

13. Analyze the investment sentiment of retail and institutional investors (get_investor_sentiment)

Analyze the investment sentiment of retail and institutional investors.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

14. Get the shareholder information of a specified stock (get_shareholder_info)

Get the shareholder information of a stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

15. Get the main product or business composition of a specified stock company (get_product_info)

Get the product information of a stock company.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

16. Get the performance forecast data of a stock, including the forecasted annual net profit and earnings per share (get_profit_forecast)

Get the performance forecast data of a stock.

Parameters:

• symbol (string): Stock code (e.g., '600519').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

17. Get the details of stock dividends and bonus issues (get_stock_fhps_detail)

Get the details of stock dividends and bonus issues of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

18. Get the chip distribution data of a stock (get_stock_cyq)

Get the chip distribution data of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• date (string): Query date in the format of YYYY-MM-DD.
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

19. Get the research reports of a stock (get_stock_research_report)

Get the research reports of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

20. Get the tradable shareholder data of a stock (get_stock_circulate_stock_holder)

Get the tradable shareholder data of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

21. Get the management change data of a stock (get_stock_management_change)

Get the management change data of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

22. Get the restricted share release data of a stock (get_stock_restricted_release_queue)

Get the restricted share release data of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

23. Get the codes and names of A-shares (get_stock_a_code_name)

Get the codes and names of all A-shares.

Parameters:

• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

24. Get the valuation data of a stock (get_stock_value)

Get the valuation data of a specified stock.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

25. Calculate the volatility indicator of a specified stock (get_stock_volatility)

Calculate the volatility indicator of a specified stock through minute-level historical market data.

Parameters:

• symbol (string): Stock code (e.g., '000001').
• start_date (string): Start date.
• end_date (string): End date.
• period (int): Time period in minutes (e.g., '1', '5', '15', '30', '60').
• adjust (string): Restoration type: none, qfq (front restoration), hfq (back restoration). Default: 'none'.
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

26. Get the codes and basic information of all indices (get_all_cni_indices)

Get the codes and basic information of all indices, removing real-time changing data and supporting caching.

Parameters:

• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

27. Get the daily historical market data of a specified index (get_cni_index_hist)

Get the daily historical market data of a specified index.

Parameters:

• symbol (string): Index code (e.g., '399005').
• start_date (string): Start date in the format of YYYYMMDD (e.g., '20230114').
• end_date (string): End date in the format of YYYYMMDD (e.g., '20240114').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

28. Get the details of the constituent stocks of a specified index (get_cni_index_detail)

Get the details of the constituent stocks of a specified index.

Parameters:

• symbol (string): Index code (e.g., '399001').
• date (string): Date in the format of YYYYMM (e.g., '202404').
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

29. Get the data of technical stock selection indicators, including new highs, new lows, consecutive rises, consecutive falls, continuous volume increase, continuous volume decrease, upward breakthrough, downward breakthrough, volume and price increase together, volume and price decrease together, and insurance capital stake increases. (get_stock_technical_rank)

Parameters:

• indicator_name (string): Name of the technical indicator to be obtained (e.g., new high - monthly new high, new high - semi-annual new high, new high - annual new high, new high - historical new high, new low - monthly new low, new low - semi-annual new low, new low - annual new low, new low - historical new low, consecutive rises, consecutive falls, continuous volume increase, continuous volume decrease, upward breakthrough - 5-day moving average, upward breakthrough - 10-day moving average, upward breakthrough - 20-day moving average, upward breakthrough - 30-day moving average, upward breakthrough - 60-day moving average, upward breakthrough - 90-day moving average, upward breakthrough - 250-day moving average, upward breakthrough - 500-day moving average, downward breakthrough - 5-day moving average, downward breakthrough - 10-day moving average, downward breakthrough - 20-day moving average, downward breakthrough - 30-day moving average, downward breakthrough - 60-day moving average, downward breakthrough - 90-day moving average, downward breakthrough - 250-day moving average, downward breakthrough - 500-day moving average, volume and price increase together, volume and price decrease together, insurance capital stake increases).
• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

30. Get the real-time market data of all industry sectors (get_stock_board_industry_summary)

Parameters:

• output_format (Literal): Output data format: json, csv, xml, excel, markdown, html. Default: 'markdown'.

🚀 Quick Start

Method 1: Use Smithery

Automatically install it to Claude Desktop via Smithery:

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

Method 2: Use Docker

1. Pull the image

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

2. Run the container

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

Method 3: Install from local source code

1. Environment requirements

• Python 3.12+
• Git
• uv (recommended Python package manager)

2. Clone the repository

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

3. Install dependencies

# It is recommended to use the uv package manager
uv sync

# Or use pip
pip install -r requirements.txt

4. Run the server

stdio mode (default, suitable for local MCP clients):

uv run -m china_stock_mcp

HTTP mode (suitable for remote access):

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

The server will be available at http://localhost:8081/mcp.

⚙️ MCP Configuration Examples

Claude Desktop Configuration

Edit claude_desktop_config.json:

Method 1: Local source code

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

Method 2: Through uvx

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

Method 3: HTTP mode

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

Other AI Client Configurations

Cursor:

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

Clion with MCP:

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

🏃‍♂️ Command-line Parameters

• --streamable-http: Enable HTTP streamable mode (default: stdio mode).
• --host: Bound host in HTTP mode (default: 0.0.0.0).
• --port: Listening port in HTTP mode (default: 8081).

📊 Data Support Scope

Stock Markets

• A-shares (Shanghai and Shenzhen)
• B-shares
• H-shares (Hong Kong stocks)
• Small and medium-sized board, Growth Enterprise Market, New Third Board

Data Types

• Historical market data (minute-level, hour-level, day-level, week-level, month-level, year-level)
• Real-time market data
• Technical indicator calculation
• News and information
• Financial statements (balance sheets, income statements, cash flow statements)
• Financial indicators
• Insider trading data

🔧 Development and Contribution

Development Environment Setup

1. Clone the repository

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

2. Install development dependencies

uv sync --dev

3. Enter development mode

uv run -m china_stock_mcp

Code Structure

src/china_stock_mcp/
├── __init__.py
├── __main__.py    # Command-line entry, handling startup parameters
├── server.py      # Core of the MCP server, defining all tools
├── mcp.json       # MCP configuration specification (optional)
└── py.typed       # Type annotation file

Adding New Tools

Use the @mcp.tool decorator in server.py to add new tools:

@mcp.tool(name="Chinese name of the tool", description="Chinese description of the tool")
def your_tool_name(param1: Annotated[str, Field(description="Parameter description")]) -> str:
    """Detailed description of the tool"""
    # Implementation logic
    pass

📄 License

MIT License - See the LICENSE file for details.

🤝 Contribution

Welcome to submit Issues and Pull Requests!

🙋‍♂️ Frequently Asked Questions

Q: Why can't I get the data? A: Please check your network connection and the availability of the data sources. Some data sources may have access restrictions.

Q: Why can't I connect in HTTP mode? A: Make sure that port 8081 is not occupied by other services and that the firewall allows access to the corresponding port.

Q: How can I update to the latest version? A: If you installed it using Smithery, it can be automatically updated. If you installed it manually, please pull the latest repository code again.

🐞 Debugging

For detailed information on how to debug this server using @modelcontextprotocol/inspector, please refer to DEBUG.md.