Content
# pytdx-mcp
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
**pytdx-mcp** is an MCP (Model Context Protocol) server based on [pytdx](https://github.com/rainx/pytdx) for obtaining real-time A-share market data.
## Features
- 🔄 **Real-time Quotes** - Get real-time prices, volumes, and other data for A-shares
- 📊 **Batch Queries** - Retrieve quotes for multiple stocks at once for increased efficiency
- 📈 **K-line Data** - Supports various K-line types such as daily and minute lines
- 🚀 **Auto Reconnect** - Intelligently selects available servers and automatically fails over
- 💰 **Completely Free** - No API keys or registration required
- 🔌 **MCP Integration** - Seamlessly integrates with large language model applications that support MCP
## Installation
### Method 1: Install from GitHub (Recommended)
```bash
pip install git+https://github.com/hasson827/pytdx-mcp.git
```
### Method 2: Install from Source
```bash
git clone https://github.com/hasson827/pytdx-mcp.git
cd pytdx-mcp
pip install -e .
```
### Verify Installation
```bash
pytdx-mcp --help
```
## Configuration
### OpenCode Configuration
Edit `~/.config/opencode/opencode.json` and add:
```json
{
"mcpServers": {
"pytdx-mcp": {
"type": "local",
"command": ["pytdx-mcp"],
"enabled": true
}
}
}
```
### Claude Desktop Configuration
Edit the Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add the following content:
```json
{
"mcpServers": {
"pytdx-mcp": {
"command": "pytdx-mcp"
}
}
}
```
## Available Tools
### 1. `get_realtime_quote` - Get Real-time Quote for a Single Stock
Retrieves real-time price, volume, and other information for a specified stock.
**Parameters:**
- `market` (int): Market code
- `0` = Shenzhen A-shares (including ChiNext)
- `1` = Shanghai A-shares (including STAR Market)
- `code` (str): Stock code (e.g., `"300766"`, `"600126"`)
**Returned Data:**
```json
{
"code": "300766",
"name": "每日互动",
"price": 44.57,
"open": 44.00,
"high": 45.20,
"low": 43.80,
"last_close": 44.41,
"vol": 248869,
"amount": 110123456.78,
"change_pct": 0.36
}
```
### 2. `get_batch_quotes` - Get Batch Quotes for Multiple Stocks
Retrieves real-time quotes for multiple stocks at once, improving efficiency.
**Parameters:**
- `stocks` (List[Dict]): List of stocks, each element containing:
- `market` (int): Market code
- `code` (str): Stock code
**Example:**
```python
stocks = [
{"market": 0, "code": "300766"}, # 每日互动
{"market": 1, "code": "688316"}, # 青云科技
]
```
### 3. `get_kline_data` - Get K-line Data
Retrieves historical K-line data for a stock, including daily and minute lines.
**Parameters:**
- `market` (int): Market code
- `code` (str): Stock code
- `kline_type` (int): K-line type
- `9` = Daily line
- `5` = 5-minute line
- `8` = 60-minute line
- `count` (int): Number of K-lines to retrieve (default 100)
## Usage Examples
### Example 1: Get Quote for a Single Stock
```
Please use pytdx-mcp to query the latest price of 每日互动 (300766)
```
### Example 2: Batch Query Multiple Stocks
```
Use pytdx-mcp to batch query the real-time quotes for the following stocks:
- 每日互动 (300766) - Shenzhen Stock Exchange
- 青云科技 (688316) - Shanghai Stock Exchange
- 杭钢股份 (600126) - Shanghai Stock Exchange
```
### Example 3: Get K-line Data
```
Use pytdx-mcp to get the daily K-line data for 每日互动 for the last 100 days
```
## Market Code Table
| Market | Code | Description |
|------|------|------|
| Shenzhen A-shares | 0 | Includes Main Board, SME Board, and ChiNext |
| Shanghai A-shares | 1 | Includes Main Board and STAR Market |
**Common Stock Codes:**
- 每日互动: Market 0, Code 300766
- 青云科技: Market 1, Code 688316
- 杭钢股份: Market 0, Code 600126
- 航锦科技: Market 0, Code 000818
## ⚙️ Technical Details
### Server Connection
pytdx-mcp uses the following strategies to ensure a stable connection:
1. **Automatic Server Selection** - Maintains multiple backup server addresses
2. **Failover** - Automatically switches when the current server is unavailable
3. **Long Connection** - Maintains the connection to improve performance
4. **Automatic Reconnection** - Automatically resets and retries when the connection fails
### Backup Server List
```
218.75.126.9:7709 # Hangzhou
115.238.56.198:7709 # Shanghai
115.238.90.165:7709 # Shanghai
218.108.50.178:7709 # Hangzhou
140.207.198.6:7709 # Shanghai
```
## Notes
1. **Trading Hours** - A-share trading hours are 9:30-11:30, 13:00-15:00
2. **Query Frequency** - It is recommended to have an interval of ≥3 seconds between each query to avoid being IP-banned
3. **Data Delay** - Free data may have a delay of 1-3 seconds
4. **For Learning Purposes Only** - Do not use for commercial purposes or real trading
## Related Projects
- [pytdx](https://github.com/rainx/pytdx) - TDX data interface
- [fastmcp](https://github.com/anthropics/fastmcp) - Fast MCP development framework
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
## Contribution
Welcome to submit Issues and Pull Requests!
## Acknowledgments
- [pytdx](https://github.com/rainx/pytdx) provides the TDX data interface
- [fastmcp](https://github.com/anthropics/fastmcp) provides the MCP development framework
---
**Disclaimer:** This project is for learning and research purposes only and does not constitute any investment advice. Please abide by relevant laws and regulations when using the data obtained from this tool.
