Content
<div align="center">
# 📊 a-share-mcp 📈
<img src="https://img.shields.io/badge/A股数据-MCP%20工具-E6162D?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiB2aWV3Qm94PSIwIDAgMjQgMjQiPg0KPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTggMTAuOGMwIDAgMC44LTEuNSAyLjQtMS41IDEuNyAwIDIuOCAxLjUgNC44IDEuNSAxLjcgMCAyLjgtMC42IDIuOC0wLjZ2LTIuMmMwIDAtMS4xIDEuMS0yLjggMS4xLTIgMC0zLjEtMS41LTQuOC0xLjUtMS42IDAtMi40IDAuOS0yLjQgMC45djIuM3pNOCAxNC44YzAgMCAwLjgtMS41IDIuNC0xLjUgMS43IDAgMi44IDEuNSA0LjggMS41IDEuNyAwIDIuOC0wLjYgMi44LTAuNnYtMi4yYzAgMC0xLjEgMS4xLTIuOCAxLjEtMiAwLTMuMS0xLjUtNC44LTEuNS0xLjYgMC0yLjQgMC45LTIuNCAwLjl2Mi4zeiI+PC9wYXRoPg0KPC9zdmc+">
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/uv)
[](https://github.com/model-context-protocol/mcp-spec)
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,15,20,24&height=200§ion=header&text=A%20股%20MCP&fontSize=80&fontAlignY=35&desc=基于%20Model%20Context%20Protocol%20(MCP)&descAlignY=60&animation=fadeIn" />
</div>
A-share MCP.
This project is an MCP (Model Context Protocol) server focused on the A-share market. It provides various query functions such as stock basic information, historical K-line data, financial indicators, macroeconomic data, etc. Theoretically, it can answer any questions related to the A-share market, whether regarding the overall market or specific stocks.
<div align="center">
<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" width="100%">
</div>
## Project Structure
```
a_share_mcp/
│
├── mcp_server.py # Main server entry file
├── pyproject.toml # Project dependency configuration
├── README.md # Project documentation
│
├── src/ # Source code directory
│ ├── __init__.py
│ ├── baostock_data_source.py # Implementation of Baostock data source
│ ├── data_source_interface.py # Data source interface definition
│ ├── utils.py # Common utility functions
│ │
│ ├── formatting/ # Data formatting module
│ │ ├── __init__.py
│ │ └── markdown_formatter.py # Markdown formatting tool
│ │
│ └── tools/ # MCP tool module
│ ├── __init__.py
│ ├── base.py # Basic utility functions
│ ├── stock_market.py # Stock market data tools
│ ├── financial_reports.py # Financial reports tools
│ ├── indices.py # Index-related tools
│ ├── market_overview.py # Market overview tools
│ ├── macroeconomic.py # Macroeconomic data tools
│ ├── date_utils.py # Date utilities
│ └── analysis.py # Analysis tools
│
└── resource/ # Resource files
└── img/ # Image resources
├── img_1.png # CherryStudio configuration example
└── img_2.png # CherryStudio configuration example
```
<div align="center">
<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" width="100%">
</div>
## Features
<div align="center">
<table>
<tr>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/stocks-growth.png" width="30px"/><br><b>Stock Basic Data</b></td>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/line-chart.png" width="30px"/><br><b>Historical Market Data</b></td>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/bonds.png" width="30px"/><br><b>Financial Statement Data</b></td>
</tr>
<tr>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/economic-improvement.png" width="30px"/><br><b>Macroeconomic Data</b></td>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/statistics.png" width="30px"/><br><b>Index Constituents</b></td>
<td align="center"><img src="https://img.icons8.com/fluency/48/null/fine-print.png" width="30px"/><br><b>Data Analysis Reports</b></td>
</tr>
</table>
</div>
## Prerequisites
1. **Python Environment**: Python 3.10+
2. **Dependency Management**: Use the `uv` package manager to install dependencies
3. **Data Source**: Based on Baostock 数据源 (Baostock data source), no paid account is required. Special thanks to Baostock.
4. Reminder: This project is developed in a Windows environment.
## Data Update Time
> The following are the official data update times from Baostock. Please pay attention to the time point when querying the latest data on the [Baostock official website](http://baostock.com/baostock/index.php/%E9%A6%96%E9%A1%B5).
**Daily Data Update Time:**
- Current trading day 17:30, completion of daily K-line data storage
- Current trading day 18:00, completion of adjusted factor data storage
- Second natural day 11:00, completion of minute K-line data storage
- Second natural day 1:30, completion of the previous trading day's "other financial report data" storage
- Saturday 17:30, completion of weekly data storage
**Weekly Data Update Time:**
- Every Monday afternoon, completion of the Shanghai Stock Exchange 50 constituent stocks, CSI 300 constituent stocks, and CSI 500 constituent stocks information data storage
> Therefore, on the trading day itself, if you inquire about the day's data before 17:30, it will not be available.
## Installation Environment
Execute in the project root directory:
To start the A-share MCP Server, please follow the steps below:
```bash
# 1. Create a virtual environment (only creates, does not install any packages)
uv venv
# 2. Activate the Virtual Environment
# Windows
.venv\Scripts\activate
# macOS/Linux
# source .venv/bin/activate
# 3. Install all dependencies (must be executed in the activated virtual environment)
uv sync
```
## Usage: Configuring the Server in the MCP Client
In MCP-supported clients (such as the VS Code plugin, CherryStudio, etc.), you need to configure how to start this server. **It is recommended to use `uv`**.
### Method 1: Using JSON Configuration in IDEs (e.g., Cursor, VSCode, Trae, etc.)
For clients that need to edit JSON files to configure the MCP Server, you need to find the corresponding place to configure MCP (different IDEs and desktop MCP Clients may vary) and add a new entry in the `mcpServers` object.
**JSON Configuration Example (please replace the path with your actual absolute path):**
```json
{
"mcpServers": {
"a-share-mcp": {
"command": "uv", // or the absolute path to uv.exe, e.g., "C:\\path\\to\\uv.exe"
"args": [
"--directory",
"C:\\Users\\YourName\\Projects\\a_share_mcp", // replace with the absolute path to your project root, it doesn't have to be on C drive, fill in as applicable
"run",
"python",
"mcp_server.py"
],
"transport": "stdio"
// "workingDirectory": "C:\\Users\\YourName\\Projects\\a_share_mcp", // this may no longer be necessary after using uv --directory, but it's recommended to keep it as a backup
}
// ... other servers ...
}
}
```
**Notes:**
- **`command`**: Ensure that the `uv` command or the absolute path to `uv.exe` is accessible and executable by the client.
- **`args`**: Ensure that the argument list is complete and in the correct order.
- **Path Escaping**: Paths need to be written with double backslashes `\\`.
> This is specific to Windows systems. If you are on macOS or Linux, paths use forward slashes / as directory separators, so no escaping is needed.
- **`workingDirectory`**: Although `uv --directory` should resolve the working directory issue, if the client still reports a `ModuleNotFoundError`, you can try explicitly setting this to the absolute path of the project root in the client configuration.
### Method 2: Using CherryStudio
In the MCP server configuration interface of CherryStudio, fill in as follows:
- **Name**: `a-share-mcp` (or customize)
- **Description**: `Local A-share MCP server` (or customize)
- **Type**: Select **Standard Input/Output (stdio)**
- **Command**: `uv` (or fill in the absolute path of uv.exe in the system)
- **Package Management Source**: Default
- **Parameters**:
1. First parameter: `--directory`
2. Second parameter: `C:\\Users\\YourName\\Projects\\a_share_mcp`
3. Third parameter: `run`
4. Fourth parameter: `python`
5. Fifth parameter: `mcp_server.py`
- _Make sure all parameters are separated by pressing Enter, otherwise an error will occur (Is this a step-by-step tutorial?)_
- **Environment Variables**: (usually left blank)
> Tricks (Must-read):
> Sometimes after filling in the parameters in CherryStudio, clicking the switch button in the upper right corner may not yield any response. In this case, simply click any button in the left directory to exit the MCP settings interface, then return to the MCP settings interface, and you will find that the MCP has successfully configured with a flashing green light.
**CherryStudio Usage Example:**
Theoretically, you can ask any questions related to A-shares :)
**Important Notes:**
- Ensure that the `uv` in the **Command** field or its absolute path is valid and executable.
- Ensure that the **Parameters** field has the five parameters filled in correctly and in order.
## Tool List
The MCP Server currently provides **41** tools, covering a comprehensive range of data including stocks, financial reports, macroeconomic data, and date analysis. Below is the complete list:
<div align="center">
<details>
<summary><b>🔍 Expand to view all tools</b></summary>
<br>
<table>
<tr>
<th>🏛️ Stock Market Data (Stock)</th>
<th>📊 Financial Statement Data (Finance)</th>
</tr>
<tr valign="top">
<td>
<ul>
<li><code>get_historical_k_data</code> (Historical K-line)</li>
<li><code>get_stock_basic_info</code> (Basic Information)</li>
<li><code>get_dividend_data</code> (Dividend Distribution)</li>
<li><code>get_adjust_factor_data</code> (Adjustment Factor)</li>
</ul>
</td>
<td>
<ul>
<li><code>get_profit_data</code> (Profitability)</li>
<li><code>get_operation_data</code> (Operational Capability)</li>
<li><code>get_growth_data</code> (Growth Capability)</li>
<li><code>get_balance_data</code> (Balance Sheet)</li>
<li><code>get_cash_flow_data</code> (Cash Flow)</li>
<li><code>get_dupont_data</code> (DuPont Analysis)</li>
<li><code>get_performance_express_report</code> (Performance Express Report)</li>
<li><code>get_forecast_report</code> (Performance Forecast)</li>
<li><code>get_fina_indicator</code> (Financial Indicator Summary)</li>
</ul>
</td>
</tr>
<tr>
<th>🔎 Market & Index (Market & Index)</th>
<th>🌐 Macro & Others (Macro & Utils)</th>
</tr>
<tr valign="top">
<td>
<ul>
<li><code>get_trade_dates</code> (Trading Calendar)</li>
<li><code>get_all_stock</code> (All Market Securities)</li>
<li><code>search_stocks</code> (Stock Search)</li>
<li><code>get_suspensions</code> (Suspension Information)</li>
<li><code>get_stock_industry</code> (Industry Classification)</li>
<li><code>get_index_constituents</code> (Index Constituents)</li>
<li><code>get_sz50_stocks</code> (SSE 50)</li>
<li><code>get_hs300_stocks</code> (CSI 300)</li>
<li><code>get_zz500_stocks</code> (CSI 500)</li>
<li><code>list_industries</code> (Industry List)</li>
<li><code>get_industry_members</code> (Industry Stocks)</li>
</ul>
</td>
<td>
<ul>
<li><code>get_deposit_rate_data</code> (Deposit Rate)</li>
<li><code>get_loan_rate_data</code> (Loan Rate)</li>
<li><code>get_required_reserve_ratio_data</code> (Required Reserve Ratio)</li>
<li><code>get_money_supply_data_month</code> (Monthly Money Supply)</li>
<li><code>get_money_supply_data_year</code> (Annual Money Supply)</li>
<li><code>get_latest_trading_date</code> (Latest Trading Day)</li>
<li><code>get_market_analysis_timeframe</code> (Intelligent Analysis Timeframe)</li>
<li><code>is_trading_day</code> (Determine Trading Day)</li>
<li><code>previous_trading_day</code> (Previous Trading Day)</li>
<li><code>next_trading_day</code> (Next Trading Day)</li>
<li><code>get_last_n_trading_days</code> (Last N Days)</li>
<li><code>get_recent_trading_range</code> (Recent Range)</li>
<li><code>get_month_end_trading_dates</code> (Month-End Trading Days)</li>
<li><code>get_stock_analysis</code> (Generate Analysis Report)</li>
<li><code>normalize_stock_code</code> (Code Normalization)</li>
<li><code>normalize_index_code</code> (Index Code Normalization)</li>
<li><code>list_tool_constants</code> (Constant Query)</li>
</ul>
</td>
</tr>
</table>
</details>
</div>
## Contribution Guidelines
We welcome you to submit Issues or Pull Requests to help improve the project. Before contributing, please take a look at the existing Issues and documentation.
## ☕️ Treat the author to a cup of coffee
If this project has been helpful to you, feel free to buy me a cup of coffee ❤️
<img src="resource/img/ali.png" alt="Alipay QR code" width="300"/>
## License
This project is licensed under the MIT License - see the LICENSE file for details.
<div align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=12,15,20,24§ion=footer&height=100&animation=fadeIn" />
</div>
## Overview of This Update (2025-12-25)
This update introduces the **Financial Metrics Aggregation Tool**, which consolidates six categories of financial data into a convenient query interface.
### 🆕 New Tools
- **Financial Indicator Summary**: `get_fina_indicator` allows you to obtain six major categories of financial indicators (profitability, operating ability, growth ability, solvency, cash flow, DuPont analysis) with a single click, returning consolidated data on a quarterly basis.
