Content
<div align="center">
# 📊 a-share-mcp 📈
<img src="https://img.shields.io/badge/A%20stock%20data-MCP%20tool-E6162D?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiB2aWV3Qm94PSIwIDAgMjQgMjQiPg0KPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTggMTAuOGMwIDAgMC44LTEuNSAyLjQtMS41IDEuNyAwIDIuOCAxLjUgNC44IDEuNSAxLjcgMCAyLjgtMC42IDIuOC0wLjZ2LTIuMmMwIDAtMS4xIDEuMS0yLjggMS4xLTIgMC0zLjEtMS41LTQuOC0xLjUtMS42IDAtMi40IDAuOS0yLjQgMC45djIuM3pNOCAxNC44YzAgMCAwLjgtMS41IDIuNC0xLjUgMS43IDAgMi44IDEuNSA0LjggMS41IDEuNyAwIDIuOC0wLjYgMi44LTAuNnYtMi4yYzAgMC0xLjEgMS4xLTIuOCAxLjEtMiAwLTMuMS0xLjUtNC48LTEuNS0xLjYgMC0yLjQgMC45LTIuNCAwLjl2Mi4zeiI+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%20stock%20MCP&fontSize=80&fontAlignY=35&desc=Based%20on%20Model%20Context%20Protocol%20(MCP)&descAlignY=60&animation=fadeIn" />
</div>
A stock 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, macroeconomic data, etc. Theoretically, it can answer any questions related to the A-share market, whether it's about the market as a whole 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 # General 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>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 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 Report</b></td>
</tr>
</table>
</div>
## Prerequisites
1. **Python Environment**: Python 3.10+
2. **Dependency Management**: Install dependencies using `uv` package manager
3. **Data Source**: Based on Baostock data source, no paid account required. Thanks to Baostock.
4. Note: This project was developed in a Windows environment.
## Data Update Time
> The following is the Baostock official data update time, please note the time point when querying the latest data [Baostock Official Website](http://baostock.com/baostock/index.php/%E9%A6%96%E9%A1%B5)
**Daily Data Update Time:**
- Current trading day 17:30, complete daily K-line data entry
- Current trading day 18:00, complete adjusted factor data entry
- Second natural day 11:00, complete minute K-line data entry
- Second natural day 1:30, complete previous trading day "other financial report data" entry
- Saturday 17:30, complete weekly data entry
**Weekly Data Update Time:**
- Every Monday afternoon, complete SSE 50 constituents, SZSE 300 constituents, CSI 500 constituents information data entry
> So, on a trading day, if it's before 17:30, you can't get the data for that day.
## Installation
To start the A-share MCP server, follow these steps:
```bash
# 1. Create a virtual environment (only create, no packages installed)
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-compatible client (such as VS Code plugin, CherryStudio, etc.), you need to configure how to start this server. **Recommended to use `uv`**.
### Method 1: Using JSON Configuration for IDEs (e.g., Cursor, VSCode, Trae, etc.)
For clients that require editing a JSON file to configure the MCP server, find the corresponding place to configure MCP (varies across IDEs and desktop MCP clients), and add a new entry to the `mcpServers` object.
**JSON Configuration Example (replace paths with your actual absolute paths):**
```json
{
"mcpServers": {
"a-share-mcp": {
"command": "uv", // or absolute path to uv.exe, e.g., "C:\\path\\to\\uv.exe"
"args": [
"--directory",
"C:\\Users\\YourName\\Projects\\a_share_mcp", // replace with your project root directory absolute path
"run",
"python",
"mcp_server.py"
],
"transport": "stdio"
// "workingDirectory": "C:\\Users\\YourName\\Projects\\a_share_mcp", // not necessary with uv --directory, but recommended as a backup
}
// ... other servers ...
}
}
```
**Notes:**
- **`command`**: Ensure the `uv` command or absolute path to `uv.exe` is valid and executable.
- **`args`**: Ensure the argument list is complete and in the correct order.
- **Path Escaping**: Paths should be written with double backslashes `\\`.
> This is specific to Windows. On macOS or Linux, paths use forward slashes `/` as directory separators, so no escaping is needed.
- **`workingDirectory`**: Although `uv --directory` should handle the working directory, if the client still reports a `ModuleNotFoundError`, try setting this to the absolute path of the project root directory.
### Method 2: Using CherryStudio
In CherryStudio's 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 absolute path to uv.exe)
- **Package Management Source**: Default
- **Arguments**:
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`
- _Ensure all parameters are separated by newlines, otherwise it will error._
- **Environment Variables**: (usually left blank)
> Tricks:
> Sometimes after filling in the parameters in CherryStudio and clicking the switch button in the top right corner, you might not see any reaction. In this case, just click any button on the left directory, jump out of the MCP settings interface, and then go back to the MCP settings interface. You will see that MCP has successfully configured with a green light.
**CherryStudio Usage Example:**
Theoretically, you can ask any questions about A-shares :)
**Important Notes:**
- Ensure the **`command`** field `uv` or its absolute path is valid and executable.
- Ensure the **`arguments`** field is correctly filled with the five parameters in order.
## Tool List
The MCP server currently provides **41** tools, covering comprehensive data such as stocks, financial reports, macroeconomics, and date analysis. Here is the complete list:
<div align="center">
<details>
<summary><b>🔍 Expand to view all tools</b></summary>
<br>
<table>
<tr>
<th>🏛️ Stock Market Data</th>
<th>📊 Financial Statement Data</th>
</tr>
<tr valign="top">
<td>
<ul>
<li><code>get_historical_k_data</code></li>
<li><code>get_stock_basic_info</code></li>
<li><code>get_dividend_data</code></li>
<li><code>get_adjust_factor_data</code></li>
</ul>
</td>
<td>
<ul>
<li><code>get_profit_data</code></li>
<li><code>get_operation_data</code></li>
<li><code>get_growth_data</code></li>
<li><code>get_balance_data</code></li>
<li><code>get_cash_flow_data</code></li>
<li><code>get_dupont_data</code></li>
<li><code>get_performance_express_report</code></li>
<li><code>get_forecast_report</code></li>
<li><code>get_fina_indicator</code></li>
</ul>
</td>
</tr>
<tr>
<th>🔎 Market & Index</th>
<th>🌐 Macro & Utils</th>
</tr>
<tr valign="top">
<td>
<ul>
<li><code>get_trade_dates</code></li>
<li><code>get_all_stock</code></li>
<li><code>search_stocks</code></li>
<li><code>get_suspensions</code></li>
<li><code>get_stock_industry</code></li>
<li><code>get_index_constituents</code></li>
<li><code>get_sz50_stocks</code></li>
<li><code>get_hs300_stocks</code></li>
<li><code>get_zz500_stocks</code></li>
<li><code>list_industries</code></li>
<li><code>get_industry_members</code></li>
</ul>
</td>
<td>
<ul>
<li><code>get_deposit_rate_data</code></li>
<li><code>get_loan_rate_data</code></li>
<li><code>get_required_reserve_ratio_data</code></li>
<li><code>get_money_supply_data_month</code></li>
<li><code>get_money_supply_data_year</code></li>
<li><code>get_latest_trading_date</code></li>
<li><code>get_market_analysis_timeframe</code></li>
<li><code>is_trading_day</code></li>
<li><code>previous_trading_day</code></li>
<li><code>next_trading_day</code></li>
<li><code>get_last_n_trading_days</code></li>
<li><code>get_recent_trading_range</code></li>
<li><code>get_month_end_trading_dates</code></li>
<li><code>get_stock_analysis</code></li>
<li><code>normalize_stock_code</code></li>
<li><code>normalize_index_code</code></li>
<li><code>list_tool_constants</code></li>
</ul>
</td>
</tr>
</table>
</details>
</div>
## Contribution Guide
Welcome to submit issues or pull requests to help improve the project. Please review existing issues and documentation before contributing.
## ☕️ Support the Author
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>
## Update Overview (2025-12-25)
This update adds a new tool, **Financial Indicator Summary**, which aggregates six categories of financial data into a convenient query interface.
### 🆕 New Tool
- **Financial Indicator Summary**: `get_fina_indicator` provides six categories of financial indicators (profitability, operational capacity, growth capacity, debt-paying ability, cash flow, and DuPont analysis) in a single query, returning consolidated data by quarter.
