Content
# Tool List
Based on [pysnowball](https://pypi.org/project/pysnowball/), a Snowball stock data server that supports both **MCP protocol** and **REST API**, deployable to Vercel with one click.
## Features
- **51 API Interfaces** - Covering real-time quotes, financial data, funds, indices, etc.
- **Dual Protocol Support** - MCP protocol + REST API, meeting different scenario needs
- **Multiple Transmission Methods** - Local stdio (recommended) + Remote Streamable HTTP (stateless)
- **Local Priority** - stdio mode without session limits, best stability
- **Swagger Documentation** - Automatically generated, out-of-the-box
- **API Authentication** - Optional `x-api-key` protection
- **One-Click Deployment** - Supports Vercel Serverless deployment (REST API)
## Quick Start
### 1. Install Dependencies
```bash
pip install -r requirements.txt
```
### 2. Configure Environment Variables
```bash
# Required: Snowball token
export XUEQIU_TOKEN=your_xueqiu_token
# Optional: API access key (requires x-api-key authentication after setting)
export API_TOKEN=your_api_key
```
> **Get Snowball Token:** Log in to [Snowball](https://xueqiu.com) → F12 Developer Tools → Application → Cookies → `xq_a_token`
### 3. Start the Service
```bash
python server.py
```
- Swagger UI: http://localhost:8000/docs
- MCP Endpoint: http://localhost:8000/mcp (Streamable HTTP)
## Deploy to Vercel
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fpdone%2Fxqmcp)
1. Fork this project to your GitHub
2. Import the project to [Vercel](https://vercel.com)
3. Add environment variables:
- `XUEQIU_TOKEN` (required)
- `API_TOKEN` (optional)
4. Complete deployment
Access `https://your-project.vercel.app/docs` to view Swagger documentation after deployment.
> [!NOTE]
> **Vercel** deployment has enabled MCP stateless mode (`stateless_http=True`), no session management required, and can be used normally with the MCP protocol. Each request is processed independently, without relying on session status.
## API Usage
### REST API
Each interface is an independent POST request:
```bash
# Search stock
curl -X POST "https://your-project.vercel.app/api/search_stock" \
-H "Content-Type: application/json" \
-d '{"q": "Guizhou Maotai"}'
# Get real-time quote (no authentication required)
curl -X POST "https://your-project.vercel.app/api/get_quote" \
-H "Content-Type: application/json" \
-d '{"symbol": "SH600519"}'
# Get main indicator (requires XUEQIU_TOKEN)
curl -X POST "https://your-project.vercel.app/api/get_main_indicator" \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
-d '{"symbol": "SH600519"}'
```
### MCP Protocol
Supports two transmission methods: **Local stdio (recommended)** and **Remote Streamable HTTP**.
#### Method 1: Local stdio (recommended)
Run the MCP server locally, no session limits, best stability.
1. **Get code**
```bash
git clone https://github.com/pdone/xqmcp.git
cd xqmcp
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Configure environment variables**
Create a `.env` file or set system environment variables:
```bash
# Required: Snowball token
export XUEQIU_TOKEN=your_xueqiu_token
# Optional: API access key
export API_TOKEN=your_api_key
```
4. **Configure Claude Desktop (`claude_desktop_config.json`):**
```json
{
"mcpServers": {
"pysnowball": {
"command": "python",
"args": ["path/to/stdio.py"],
"env": {
"XUEQIU_TOKEN": "your_xueqiu_token",
"API_TOKEN": "your_api_key"
}
}
}
}
```
5. **Or configure Claude Code CLI:**
```bash
claude mcp add pysnowball -- python path/to/stdio.py
```
#### Method 2: Remote Streamable HTTP
Use HTTP/HTTPS protocol, suitable for remote access scenarios. Vercel deployment supports stateless mode and can be used normally.
**Claude Desktop (`claude_desktop_config.json`):**
```json
{
"mcpServers": {
"pysnowball": {
"url": "https://your-project.vercel.app/mcp",
"headers": {
"x-api-key": "your_api_key" // Optional, can be removed if API_TOKEN is empty
}
}
}
}
```
**Claude Code CLI:**
```bash
# No authentication
claude mcp add pysnowball --transport http https://your-project.vercel.app/mcp
# With authentication
claude mcp add pysnowball --transport http https://your-project.vercel.app/mcp --header "x-api-key: your_api_key"
```
**Streamable HTTP Advantages:**
- Use standard HTTP/HTTPS protocol, penetrate firewalls and proxies
- Support bidirectional streaming
- Support session management and reconnection
- Better compatibility and stability
## Interface Classification
| Category | Number of Interfaces | Example Interfaces |
|----------|---------------------|--------------------|
| Real-time Quotes | 3 | `get_quote`, `get_pankou`, `get_quote_detail` |
| Financial Data | 9 | `get_balance`, `get_income`, `get_cash_flow` |
| Fundamentals | 11 | `get_holders`, `get_top_holders`, `get_bonus` |
| Capital Flow | 5 | `get_capital_flow`, `get_margin` |
| Research Report Data | 2 | `get_report`, `get_earningforecast` |
| Fund Data | 9 | `get_fund_detail`, `get_fund_nav_history` |
| Index Data | 6 | `get_index_basic_info`, `get_index_weight_top10` |
| Bond Data | 1 | `get_convertible_bond` |
| Hong Kong Stock Connect | 2 | `get_northbound_shareholding_sh/sz` |
| User Data | 2 | `get_watch_list`, `get_watch_stock` |
| Search | 1 | `search_stock` |
> Complete interface documentation, please visit Swagger UI: `/docs`
## Project Structure
```
xqmcp/
├── api/
│ └── index.py # Vercel entry + MCP Streamable HTTP processing
├── tools/ # Tool functions (each module corresponds to a classification)
│ ├── realtime.py # Real-time quotes
│ ├── finance.py # Financial data
│ ├── f10.py # Fundamentals
│ ├── capital.py # Capital flow
│ ├── report.py # Research report data
│ ├── fund.py # Fund data
│ ├── index.py # Index data
│ ├── bond.py # Bond data
│ ├── hkex.py # Hong Kong Stock Connect
│ ├── user.py # User data
│ ├── cube.py # Portfolio data (cleared, tool removed)
│ └── suggest.py # Search
├── mcp_server.py # MCP server core
├── stdio.py # Local stdio mode entry (recommended)
├── server.py # FastAPI server + Swagger
├── tests/ # Test scripts
├── vercel.json # Vercel deployment configuration
├── requirements.txt # Python dependencies
└── runtime.txt # Python version
```
## Environment Variables
| Variable Name | Required | Default Value | Description |
|--------------|----------|---------------|-------------|
| `XUEQIU_TOKEN` | Yes | - | Snowball login token |
| `API_TOKEN` | No | Empty | API access key, enable `x-api-key` authentication after setting |
## Technology Stack
- [pysnowball](https://pypi.org/project/pysnowball/) - Snowball data interface
- [FastAPI](https://fastapi.tiangolo.com/) - REST API framework
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - MCP protocol support (Streamable HTTP)
- [Vercel](https://vercel.com) - Serverless deployment platform
## License
MIT
