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 a 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. In theory, 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
│
├── docs/ # Project documentation
│ ├── baostock_com.md # Baostock API documentation
│ ├── mcp_server_docs.md # Server documentation
│ └── dev_docs/ # Development documentation
│ ├── AppFlow.md
│ ├── ImplementationPlan.md
│ └── PRD.md
│
├── 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 utility functions
│ ├── stock_market.py # Stock market data tools
│ ├── financial_reports.py # Financial report 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 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 Baostock data source, no paid account is required. Thanks to Baostock.
4. Note: This project was developed in a Windows environment.
## Data Update Time
> Below are the official data update times from Baostock. Please pay attention to the time points when querying the latest data [Baostock Official Website](http://baostock.com/baostock/index.php/%E9%A6%96%E9%A1%B5)
**Daily Data Update Times:**
- Current trading day 17:30, daily K-line data is stored
- Current trading day 18:00, adjustment factor data is stored
- Second natural day 11:00, minute K-line data is stored
- Second natural day 1:30, previous trading day's "other financial report data" is stored
- Saturday 17:30, weekly data is stored
**Weekly Data Update Times:**
- Every Monday afternoon, information data for the SSE 50 constituents, CSI 300 constituents, and CSI 500 constituents is stored
> Therefore, on the trading day, 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 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 a client that supports MCP (such as VS Code plugins, 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 require editing a JSON file 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 of uv.exe, e.g., "C:\\path\\to\\uv.exe"
"args": [
"--directory",
"C:\\Users\\YourName\\Projects\\a_share_mcp", // Replace with your project's root directory absolute path, not necessarily C drive, fill in according to actual situation
"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 is recommended to keep it as a backup
}
// ... other servers ...
}
}
```
**Notes:**
- **`command`**: Ensure that the `uv` command or the absolute path of `uv.exe` is accessible and executable by the client.
- **`args`**: Ensure the parameter list is complete and in the correct order.
- **Path Escaping**: Paths need to be written with double backslashes `\\`.
> This is a Windows-specific situation. If on macOS or Linux, use forward slashes / as directory separators, and no escaping is needed.
- **`workingDirectory`**: Although `uv --directory` should solve the working directory issue, if the client still reports `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`
- _Ensure all parameters are separated by pressing enter, otherwise an error will occur (is this a step-by-step guide?)_
- **Environment Variables**: (usually left blank)
> Tricks (must-read):
> Sometimes after filling in the parameters in CherryStudio and clicking the switch button in the upper right corner, nothing happens. At this point, just 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 green light.
**CherryStudio Usage Example:**
In theory, you can ask any questions related to A-shares :)
**Important Reminder:**
- Ensure that the `uv` in the **Command** field or its absolute path is valid and executable.
- Ensure that the **Parameters** field is filled in correctly in order with the five parameters.
## Tool List
This MCP server provides the following tools:
<div align="center">
<details>
<summary><b>🔍 Expand to view all tools</b></summary>
<br>
<table>
<tr>
<th>🏛️ Stock Market Data</th>
<th>📊 Financial Report Data</th>
<th>🔎 Market Overview 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>
</ul>
</td>
<td>
<ul>
<li><code>get_trade_dates</code></li>
<li><code>get_all_stock</code></li>
</ul>
</td>
</tr>
<tr>
<th>📈 Index Related Data</th>
<th>🌐 Macroeconomic Data</th>
<th>⏰ Date Tools & Analysis</th>
</tr>
<tr valign="top">
<td>
<ul>
<li><code>get_stock_industry</code></li>
<li><code>get_sz50_stocks</code></li>
<li><code>get_hs300_stocks</code></li>
<li><code>get_zz500_stocks</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__data</code></li>
</ul>
</td>
<td>
<ul>
<!-- <li><code>get_current_date</code></li> -->
<li><code>get_latest_trading_date</code></li>
<li><code>get_stock_analysis</code></li>
</ul>
</td>
</tr>
</table>
</details>
</div>
## Contribution Guidelines
Contributions are welcome! Please submit Issues or Pull Requests to help improve the project. Before contributing, please check existing Issues and documentation.
## ☕️ Buy Me a Coffee
If this project has been helpful to you, feel free to buy me a 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-09)
This update focuses on the practice of "writing efficient tools for agents," emphasizing the enhancement of tool discoverability, composability, and contextual efficiency.
### Optimizations
- Unified output: Added optional parameters limit (default 250) and format (markdown|json|csv), default remains Markdown compatible.
- Enriched context: Included meta (query parameters, as_of, returned/total row count, truncation status, column information) in the return.
- Added universal formatter: format_table_output(df, format, max_rows, meta), supports JSON { data, meta }, CSV, and Markdown with Meta summary.
- Tool encapsulation unification: The calling helpers in tools/base.py support limit/format, ensuring consistent output behavior.
### New Tools
- Index/Industry: get_index_constituents, list_industries, get_industry_members
- Market Overview: search_stocks (search by code substring), get_suspensions (suspension list)
- Date Tools: is_trading_day, previous_trading_day, next_trading_day
- Helper Tools: normalize_stock_code (standardize to sh.600000), list_tool_constants (enumerate valid values)
### Refactored Tools (added limit/format)
- Stocks: get_historical_k_data, get_stock_basic_info, get_dividend_data, get_adjust_factor_data
- Financial Reports: All quarterly tools + get_performance_express_report, get_forecast_report
- Indices: get_stock_industry, get_sz50_stocks, get_hs300_stocks, get_zz500_stocks
- Market: get_trade_dates, get_all_stock
- Macroeconomic: Deposit/Loan rates, required reserve ratio, money supply (monthly/yearly)
### Compatibility and Examples
- Backward compatibility: Tool names and required parameters remain unchanged; new parameters are optional; default output is still Markdown.
- Examples:
```
get_index_constituents(index='hs300', format='json', limit=100)
search_stocks(keyword='600', date='2025-01-10', limit=20)
get_historical_k_data(code='sh.600000', start_date='2024-01-01', end_date='2024-06-30', frequency='d', format='csv', limit=200)
previous_trading_day('2025-01-04')
normalize_stock_code('000001.SZ') # -> 'sz.000001'
```
