Pysnowball Server

基于 pysnowball 的雪球股票数据服务器，同时支持 MCP 协议 和 REST API，可一键部署到 Vercel。

功能特性

• 51 个 API 接口 - 覆盖实时行情、财务数据、基金、指数等
• 双协议支持 - MCP 协议 + REST API，满足不同场景需求
• 多传输方式 - 本地 stdio（推荐）+ 远程 Streamable HTTP（无状态）
• 本地优先 - stdio 模式无 session 限制，稳定性最佳
• Swagger 文档 - 自动生成，开箱即用
• API 认证 - 可选的 x-api-key 保护
• 一键部署 - 支持 Vercel Serverless 部署（REST API）

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

# 必填：雪球网 token
export XUEQIU_TOKEN=your_xueqiu_token

# 可选：API 访问密钥（设置后需要 x-api-key 认证）
export API_TOKEN=your_api_key

获取雪球 Token： 登录 雪球网 → F12 开发者工具 → Application → Cookies → xq_a_token

3. 启动服务

python server.py

• Swagger UI: http://localhost:8000/docs
• MCP 端点: http://localhost:8000/mcp (Streamable HTTP)

部署到 Vercel

Deploy with Vercel

1. Fork 本项目到你的 GitHub
2. 在 Vercel 导入项目
3. 添加环境变量：
   • XUEQIU_TOKEN（必填）
   • API_TOKEN（可选）
4. 完成部署

部署后访问 https://your-project.vercel.app/docs 查看 Swagger 文档。

[!NOTE] Vercel 部署已启用 MCP 无状态模式（stateless_http=True），无需 session 管理，可正常使用 MCP 协议。每个请求独立处理，不依赖会话状态。

API 使用

REST API

每个接口都是独立的 POST 请求：

# 搜索股票
curl -X POST "https://your-project.vercel.app/api/search_stock" \
  -H "Content-Type: application/json" \
  -d '{"q": "贵州茅台"}'

# 获取实时行情（无需认证）
curl -X POST "https://your-project.vercel.app/api/get_quote" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "SH600519"}'

# 获取主要指标（需要 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 协议

支持两种传输方式：本地 stdio（推荐） 和 远程 Streamable HTTP。

方式一：本地 stdio（推荐）

本地运行 MCP 服务器，无 session 限制，稳定性最佳。

1. 获取代码

   git clone https://github.com/pdone/xqmcp.git
   cd xqmcp
   

2. 安装依赖

   pip install -r requirements.txt
   

3. 配置环境变量 创建 .env 文件或设置系统环境变量：

   # 必填：雪球网 token
   export XUEQIU_TOKEN=your_xueqiu_token
   
   # 可选：API 访问密钥
   export API_TOKEN=your_api_key
   

4. 配置 Claude Desktop (claude_desktop_config.json)：

   {
     "mcpServers": {
       "pysnowball": {
         "command": "python",
         "args": ["path/to/stdio.py"],
         "env": {
           "XUEQIU_TOKEN": "your_xueqiu_token",
           "API_TOKEN": "your_api_key"
         }
       }
     }
   }
   

5. 或配置 Claude Code CLI：

   claude mcp add pysnowball -- python path/to/stdio.py
   

方式二：远程 Streamable HTTP

使用 HTTP/HTTPS 协议，适合远程访问场景。Vercel 部署已支持无状态模式，可正常使用。

Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "pysnowball": {
      "url": "https://your-project.vercel.app/mcp",
      "headers": {
        "x-api-key": "your_api_key"  // 可选，API_TOKEN 为空时可删除
      }
    }
  }
}

Claude Code CLI：

# 无认证
claude mcp add pysnowball --transport http https://your-project.vercel.app/mcp

# 带认证
claude mcp add pysnowball --transport http https://your-project.vercel.app/mcp --header "x-api-key: your_api_key"

Streamable HTTP 优势：

• 使用标准 HTTP/HTTPS 协议，穿透防火墙和代理
• 支持双向流式传输
• 支持会话管理和断线重连
• 更好的兼容性和稳定性

接口分类

分类	接口数	示例接口
实时行情	3	get_quote, get_pankou, get_quote_detail
财务数据	9	get_balance, get_income, get_cash_flow
基本面	11	get_holders, get_top_holders, get_bonus
资金流向	5	get_capital_flow, get_margin
研报数据	2	get_report, get_earningforecast
基金数据	9	get_fund_detail, get_fund_nav_history
指数数据	6	get_index_basic_info, get_index_weight_top10
债券数据	1	get_convertible_bond
港股通	2	get_northbound_shareholding_sh/sz
用户数据	2	get_watch_list, get_watch_stock
搜索	1	search_stock

完整接口文档请访问 Swagger UI: /docs

项目结构

xqmcp/
├── api/
│   └── index.py          # Vercel 入口 + MCP Streamable HTTP 处理
├── tools/                # 工具函数（每个模块对应一个分类）
│   ├── realtime.py       # 实时行情
│   ├── finance.py        # 财务数据
│   ├── f10.py            # 基本面
│   ├── capital.py        # 资金流向
│   ├── report.py         # 研报数据
│   ├── fund.py           # 基金数据
│   ├── index.py          # 指数数据
│   ├── bond.py           # 债券数据
│   ├── hkex.py           # 港股通
│   ├── user.py           # 用户数据
│   ├── cube.py           # 组合数据（已清空，工具已移除）
│   └── suggest.py        # 搜索
├── mcp_server.py         # MCP 服务器核心
├── stdio.py              # 本地 stdio 模式入口（推荐）
├── server.py             # FastAPI 服务器 + Swagger
├── tests/                # 测试脚本
├── vercel.json           # Vercel 部署配置
├── requirements.txt      # Python 依赖
└── runtime.txt           # Python 版本

环境变量

变量名	必填	默认值	说明
XUEQIU_TOKEN	是	-	雪球网登录 token
API_TOKEN	否	空	API 访问密钥，设置后启用 x-api-key 认证

技术栈

• pysnowball - 雪球数据接口
• FastAPI - REST API 框架
• MCP Python SDK - MCP 协议支持（Streamable HTTP）
• Vercel - Serverless 部署平台

License

MIT