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股mcp.
This project is an MCP server focused on the A-share market, providing various query functions such as stock basic information, historical K-line data, financial indicators, and macroeconomic data. Theoretically, it can answer any questions about the A-share market, whether for 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 # Baostock data source implementation
│ ├── 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 tool functions
│ ├── stock_market.py # Stock market data tool
│ ├── financial_reports.py # Financial report tool
│ ├── indices.py # Index-related tool
│ ├── market_overview.py # Market overview tool
│ ├── macroeconomic.py # Macroeconomic data tool
│ ├── date_utils.py # Date tool
│ └── analysis.py # Analysis tool
│
└── 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>Basic Stock 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 Report 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 the Baostock data source, no paid account is required. Thanks to Baostock.
4. Reminder: This project is developed under the Windows environment.
## Data Update Time
> The following is the official Baostock data update time. Please pay attention to the time when querying the latest data [Baostock Official Website](http://baostock.com/baostock/index.php/%E9%A6%96%E9%A1%B5)
**Daily Data Update Time:**
- 17:30 on the current trading day, the daily K-line data is completed
- 18:00 on the current trading day, the ex-right factor data is completed
- 11:00 on the second natural day, the minute K-line data is completed
- 1:30 on the second natural day, the "other financial report data" of the previous trading day is completed
- Saturday 17:30, the weekly data is completed
**Weekly Data Update Time:**
- Every Monday afternoon, the Shanghai Stock Exchange 50 constituent stocks, the Shanghai and Shenzhen 300 constituent stocks, and the CSI 500 constituent stock information data are completed.
> Therefore, on the day of the trading day, if you ask for the data of the day before 17:30, you will not be able to obtain it.
## Installation
Execute the following in the project root directory:
To start the A-share MCP server, follow these steps:
```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: Configure the server in the MCP client
In an MCP-enabled client (such as VS Code plugins, CherryStudio, etc.), you need to configure how to start this server. **It is recommended to use `uv`**.
### Method 1: Use JSON-configured IDEs (e.g., Cursor, VSCode, Trae, etc.)
For clients that require editing a JSON file to configure the MCP server, you need to find the place where you can configure MCP (each IDE and desktop MCP Client may be different), 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 of uv.exe, e.g.: "C:\\path\\to\\uv.exe"
"args": [
"--directory",
"C:\\Users\\YourName\\Projects\\a_share_mcp", // Replace with the absolute path of your project root directory, it does not have to be on the C drive, fill it in as actual
"run",
"python",
"mcp_server.py"
],
"transport": "stdio"
// "workingDirectory": "C:\\Users\\YourName\\Projects\\a_share_mcp", // After using uv --directory, this item may no longer be necessary, but it is recommended to keep it as a backup
}
// ... other servers ...
}
}
```
**Precautions:**
- **`command`**: Make sure that the absolute path of the `uv` command or `uv.exe` is accessible and executable by the client.
- **`args`**: Make sure the parameter list is complete and in the correct order.
- **Path Escaping**: Paths need to be written as double backslashes `\\`.
> This is specific to Windows systems. If you are on macOS or Linux, use forward slashes / as directory separators, and you do not need this escaping.
- **`workingDirectory`**: Although `uv --directory` should solve the working directory problem, if the client still reports `ModuleNotFoundError`, you can try explicitly setting this item to the absolute path of the project root directory in the client configuration.
### Method 2: Use CherryStudio
In the CherryStudio MCP server configuration interface, fill in as follows:
- **Name**: `a-share-mcp` (or custom)
- **Description**: `Local A-share MCP server` (or custom)
- **Type**: Select **Standard Input/Output (stdio)**
- **Command**: `uv` (or fill in uv.exe under the absolute path in the system)
- **Package Management Source**: Default
- **Parameters**:
1. Fill in the first parameter: `--directory`
2. Fill in the second parameter: `C:\\Users\\YourName\\Projects\\a_share_mcp`
3. Fill in the third parameter: `run`
4. Fill in the fourth parameter: `python`
5. Fill in the fifth parameter: `mcp_server.py`
- _Make sure that all parameters are separated by pressing Enter to change lines, otherwise an error will be reported (is this a step-by-step teaching?)_
- **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 will find that there is no response. At this time, just click any button in the left directory, pop up the mcp setting interface, and then return to the mcp setting interface, you will find that mcp has flashed green and the configuration is successful.
**CherryStudio Usage Example:**
Theoretically, you can ask any questions about A-shares :)
**Important Tips:**
- Make sure that `uv` or its absolute path in the **Command** field is valid and executable.
- Make sure that the **Parameters** field is filled in with five parameters in the correct order.
## Tool List
The MCP Server currently provides **41** tools, covering comprehensive data such as stocks, financial reports, macroeconomics, and date analysis. The following 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> (Operating Capacity)</li>
<li><code>get_growth_data</code> (Growth Capacity)</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> (Forecast Report)</li>
<li><code>get_fina_indicator</code> (Financial Indicator Summary)</li>
</ul>
</td>
</tr>
<tr>
<th>🔎 Market & Index (Market & Index)</th>
<th>🌐 Macro & Utils (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> (SZ50)</li>
<li><code>get_hs300_stocks</code> (HS300)</li>
<li><code>get_zz500_stocks</code> (ZZ500)</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> (Money Supply Month)</li>
<li><code>get_money_supply_data_year</code> (Money Supply Year)</li>
<li><code>get_latest_trading_date</code> (Latest Trading Date)</li>
<li><code>get_market_analysis_timeframe</code> (Intelligent Analysis Cycle)</li>
<li><code>is_trading_day</code> (Trading Day Judgment)</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 Dates)</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 Guide
Welcome to submit Issues or Pull Requests to help improve the project. Please check existing Issues and documentation before contributing.
## ☕️ Buy the author a coffee
If this project is helpful to you, you are welcome to buy me a coffee ❤️
<img src="resource/img/ali.png" alt="支付宝收款码" 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 adds a **financial indicator summary tool**, which aggregates 6 categories of financial data into a convenient query interface.
### 🆕 New Tool
- **Financial Indicator Summary**: `get_fina_indicator` One-click access to 6 major financial indicators (profitability, operating capacity, growth capacity, solvency, cash flow, DuPont analysis), returning merged data by quarter.
