雪球 MCP Server

把雪球的行情、财务、资金与社区论坛数据接入任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cherry Studio 等）。

覆盖 A 股 / 港股 / 美股，外加指数、ETF、可转债。共 22 个工具。

特点

• 面向大模型的输出：雪球原始接口返回的是 ncf_from_oa、1.7205417189091E11 这类字段和数值。本项目把 600+ 个财务字段翻译成中文、把金额换算成「亿元 / 万元」、把多期财报转置成「指标 × 报告期」的 Markdown 表格，模型可以直接读懂，token 消耗也远低于原始 JSON。

• 港股字段经过校验：雪球港股财报用的是 tto、plobtx、ploashh 这类高度缩写的代码。本项目的中文映射是用腾讯控股实际财报数值、通过会计恒等式反向确认的（如 tto - slgcost == gp、ta - tlia == teqy、nocf + ninvcf + nfcgcf == icdccceq），而不是靠猜。

• 论坛可用：社区接口在 xueqiu.com 主域会被风控拦截，本项目走雪球 App 使用的 api.xueqiu.com，无需登录即可读取个股讨论、公告新闻、热帖、评论。帖子正文的 HTML 会清洗成纯文本。

• 免配置：匿名令牌自动获取与续期，装完即用，不需要 Cookie、不需要注册。

• 选股指标实时同步：选股器的指标清单直接读雪球官方元数据接口，雪球调整指标不会导致本项目过时。

• 能在小机器上扛并发：分级 TTL 缓存 + 并发请求合并 + HTTP/2 多路复用。真实环境实测重复查询快 15.8 倍、打向雪球的请求减少 90%，常驻内存约 75MB。详见性能与并发。

Related MCP server: AgentSkills MCP

安装

uv venv --python 3.12 && uv pip install -e .

大 JSON（如 500 根 K 线）的解析想再快 2~3 倍，可以带上 orjson：

uv pip install -e ".[fast]"

接入 Claude Code

在项目目录下执行：

claude mcp add xueqiu -- "$(pwd)/.venv/bin/xueqiu-mcp"

接入 Claude Desktop / 其他客户端

macOS 可以直接跑安装脚本。它会自动等 Claude 完全退出（运行中的 Claude 会用内存配置覆盖该文件）、 备份原配置，并且只增改 xueqiu 一项，不动你已有的其他 MCP：

./install-claude-desktop.sh

手动配置则编辑配置文件（Claude Desktop 在 ~/Library/Application Support/Claude/claude_desktop_config.json）， 把 command 换成 .venv/bin/xueqiu-mcp 的绝对路径：

{
  "mcpServers": {
    "xueqiu": {
      "command": "/绝对路径/.venv/bin/xueqiu-mcp"
    }
  }
}

若项目路径里含空格或中文，务必使用完整的绝对路径字符串，不要拆成 args。

工具一览

搜索与行情

财务

公司资料

资金面

市场与选股

社区论坛

代码写法

也可以直接传中文名称（如「贵州茅台」），工具会先搜索再取数。

使用示例

对模型直接说：

• 「茅台最近的财务指标怎么样？」

• 「帮我筛出市盈率 20 倍以下、股息率 3% 以上、市值千亿以上的 A 股」

• 「看看雪球上大家怎么讨论宁德时代的」

• 「对比一下贵州茅台和五粮液近三年的毛利率和 ROE」

• 「腾讯今天有什么公告吗」

选股器的筛选语法：

filters="pettm:0~20,dy_l:3~,mc:100000000000~"

即市盈率 0~20 倍、股息率 3% 以上、市值 1000 亿以上。边界可留空表示不限。 指标名可用 list_screener_metrics 查询，_l 后缀表示取最新报告期。

可选：配置自己的 Cookie

绝大多数功能匿名即可使用。少数需要登录态的接口（如用户资料详情）可以配置环境变量：

export XUEQIU_COOKIE="从浏览器开发者工具复制的完整 Cookie"

在 MCP 配置里则写成：

{
  "mcpServers": {
    "xueqiu": {
      "command": "/绝对路径/.venv/bin/xueqiu-mcp",
      "env": { "XUEQIU_COOKIE": "..." }
    }
  }
}

部署到服务器

默认以 stdio 启动，一个进程只服务一个客户端。要在一台机器上同时服务多人多客户端， 改用 streamable-http：

XUEQIU_TRANSPORT=streamable-http XUEQIU_HOST=0.0.0.0 XUEQIU_PORT=8000 \
  .venv/bin/xueqiu-mcp

客户端连 http://<地址>:8000/mcp。该模式默认 stateless —— 服务端不为客户端保留会话， 内存不随连接数累积，也方便多副本横向扩展。

雪球接口没有官方开放平台，公网暴露前请自行加好鉴权与限流，也别把别人的请求量转嫁到雪球身上。

性能与并发

所有资源参数都能用环境变量压低，适配小内存机器：

缓存按 endpoint 分级：行情 3 秒、K 线 30 秒、财报 1 小时、公司资料 6 小时、 行业分类与选股指标 24 小时。并发请求同一份数据时只放一个请求出去，其余等它的结果。

实测

以下数字来自真实环境实测（打真实雪球接口，A 股交易时段，共约 1,500 次请求）：

瓶颈不在本项目：stock.xueqiu.com 单请求中位 40.4 ms，api.xueqiu.com（社区类）84.8 ms， 而本项目自身只占 4.4 ms。

收益主要来自缓存与请求合并，其次是 HTTP/2 在冷连接突发时的多路复用。 纯管道吞吐（关掉缓存）与优化前基本持平 —— 别指望靠它变快。

tests/bench.py 打的是本地 mock 上游（mock 口径，不等于真实表现）， 用途是回归检测而非标榜性能：

.venv/bin/python tests/bench.py            # 默认模拟 30ms 网络延迟
MOCK_RTT=0 .venv/bin/python tests/bench.py # 零延迟，放大纯代码开销

判读要点：关注上游请求数和峰值并发是否符合预期。QPS 数字受 mock server 自身 调度开销影响很大，本地回环上并发升高时 QPS 下降是测试环境的产物，不代表被测代码有问题。

缓存层另有一组零网络的回归测试，覆盖请求合并、取消传播、LRU 淘汰与字节记账：

.venv/bin/python tests/test_cache.py

已知边界

• 并发闸门不是限流器。它只约束「同时在途请求数」，不约束单位时间请求数。 按实测延迟，32 并发理论上允许约 700 req/s 打向雪球。请在调用侧自行控制节奏。

• 真实环境只验证到 32 并发，更高并发没有真实数据。

• XUEQIU_CACHE_MB 是偏乐观的估计，实测真实内存增长约为该值的 1.2~1.9 倍 （小条目场景偏高）。小内存机器建议设 8。

测试

.venv/bin/python tests/test_mcp_e2e.py

该脚本会以真正的 MCP 客户端身份通过 stdio 连接本 Server，列出全部工具并逐个实调 （含中文名解析、指数/ETF/可转债、以及各类参数校验的错误提示），最后打印通过数。

项目结构

src/xueqiu_mcp/
├── client.py        HTTP 客户端：令牌续期、连接池与 HTTP/2、并发闸门、风控识别
├── cache.py         响应缓存：分级 TTL、LRU 内存上限、并发请求合并
├── symbols.py       代码规范化（600519 → SH600519）
├── resolve.py       代码解析，中文名走搜索兜底
├── fields.py        A 股字段中文映射表
├── fields_intl.py   港股 / 美股字段映射表（经会计恒等式校验）
├── screener.py      选股器指标元数据（读雪球官方接口并缓存）
├── formatting.py    数值单位换算、Markdown 表格、HTML 正文清洗
├── server.py        MCP 工具注册
└── tools/
    ├── quote.py     行情、K 线、分时
    ├── finance.py   财务报表、主营构成
    ├── f10.py       公司资料、股东、分红
    ├── capital.py   资金流、两融、大宗交易
    ├── market.py    选股器、行业、人气榜
    └── social.py    论坛：讨论、公告新闻、热帖、评论

说明

• 数据全部来自雪球公开接口，行情可能有延迟，不构成任何投资建议。

• 本项目仅供学习研究，请遵守雪球的服务条款，避免高频请求。

• 雪球接口非官方开放平台，字段与可用性可能随时调整。