雪球 MCP Server

Подключает данные 雪球 по котировкам, финансам, капиталу и сообществу к любому клиенту, поддерживающему MCP (Claude Code, Claude Desktop, Cherry Studio и др.).

Охватывает A-акции / гонконгские / американские акции, а также индексы, ETF и конвертируемые облигации. Всего 22 инструмента.

Особенности

• Вывод, ориентированный на LLM: исходный API Xueqiu возвращает поля и значения вроде ncf_from_oa, 1.7205417189091E11. Этот проект переводит 600+ финансовых полей на китайский язык, пересчитывает суммы в «сотни миллионов / десятки тысяч юаней», транспонирует многоотчётные финансовые данные в Markdown-таблицы «показатель × отчётный период» — модель читает их напрямую, а расход токенов намного ниже, чем у исходного JSON.

• Поля гонконгских акций проверены: финансовая отчётность Xueqiu для Гонконга использует сильно сокращённые коды вроде tto, plobtx, ploashh. Китайские сопоставления в этом проекте подтверждены обратной проверкой по фактическим данным отчётности Tencent Holdings через бухгалтерские тождества (например, tto - slgcost == gp, ta - tlia == teqy, nocf + ninvcf + nfcgcf == icdccceq), а не угаданы.

• Форум доступен: интерфейс сообщества на основном домене xueqiu.com блокируется системой контроля рисков; этот проект использует api.xueqiu.com, который применяет приложение Xueqiu, — без входа в систему можно читать обсуждения по акциям, новости и объявления, популярные посты и комментарии. HTML тела постов очищается до простого текста.

• Без настройки: анонимный токен получается и продлевается автоматически — установил и пользуйся, не нужны ни Cookie, ни регистрация.

• Синхронизация метрик скринера в реальном времени: список метрик скринера читается напрямую из официального API метаданных Xueqiu; если Xueqiu меняет метрики, этот проект не устаревает.

• Выдерживает конкурентность на слабых машинах: многоуровневый TTL-кэш + объединение конкурентных запросов + мультиплексирование HTTP/2. В реальной среде повторные запросы быстрее в 15,8 раза, запросов к Xueqiu на 90% меньше, постоянная память около 75 МБ. Подробнее в разделе Производительность и конкурентность.

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.

Обзор инструментов

Поиск и котировки

Финансы

Данные о компании

Капитал

Рынок и скрининг акций

Сообщество

Формат кодов

Можно также передавать китайское название напрямую (например, «贵州茅台») — инструмент сначала выполнит поиск, а затем получит данные.

Примеры использования

Говорите модели напрямую:

• «Как у 茅台 последние финансовые показатели?»

• «Помоги отфильтровать A-акции с P/E ниже 20, дивидендной доходностью выше 3% и капитализацией выше 100 млрд юаней»

• «Посмотри, как на Xueqiu обсуждают 宁德时代»

• «Сравни валовую маржу и ROE 贵州茅台 и 五粮液 за последние три года»

• «Есть ли у 腾讯 сегодня какие-нибудь объявления?»

Синтаксис фильтрации скринера:

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

То есть P/E от 0~20, дивидендная доходность выше 3%, капитализация выше 100 млрд. Границы можно оставить пустыми — это означает без ограничений. Имена метрик можно посмотреть через 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 — сервер не хранит сессии для клиентов, память не растёт с числом подключений, и легко масштабироваться горизонтально несколькими репликами.

У API Xueqiu нет официальной открытой платформы. Перед публичным доступом добавьте собственную аутентификацию и ограничение частоты запросов, и не перекладывайте чужой объём запросов на Xueqiu.

Производительность и конкурентность

Все параметры ресурсов можно снизить через переменные окружения для машин с малым объёмом памяти:

Кэш разбит по уровням в зависимости от endpoint: котировки — 3 секунды, K-линии — 30 секунд, финансовая отчётность — 1 час, данные о компании — 6 часов, отраслевая классификация и метрики скринера — 24 часа. При конкурентных запросах одних и тех же данных наружу отправляется только один запрос, остальные ждут его результат.

Реальные замеры

Следующие цифры получены в реальной среде (реальные API Xueqiu, в часы торгов A-акциями, всего около 1500 запросов):

Узкое место не в этом проекте: медиана одного запроса к stock.xueqiu.com — 40,4 мс, к api.xueqiu.com (сообщество) — 84,8 мс, а сам проект занимает всего 4,4 мс.

Выигрыш в основном от кэша и объединения запросов, затем — от мультиплексирования 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-сервера; падение QPS при росте конкурентности на локальной петле — артефакт тестовой среды, а не признак проблемы в тестируемом коде.

Для слоя кэша есть ещё один набор регрессионных тестов без сети, покрывающий объединение запросов, распространение отмены, вытеснение LRU и учёт байтов:

.venv/bin/python tests/test_cache.py

Известные ограничения

• Шлюз конкурентности — не ограничитель частоты. Он ограничивает только «число одновременных запросов в пути», а не число запросов в единицу времени. По измеренным задержкам, 32 конкурентных запроса теоретически позволяют около 700 req/s в сторону Xueqiu. Контролируйте темп на стороне вызова.

• В реальной среде проверено только до 32 конкурентных запросов, для более высоких значений реальных данных нет.

• XUEQIU_CACHE_MB — скорее оптимистичная оценка; по факту реальный рост памяти составляет примерно 1.2~1.9 раза от этого значения (выше при сценарии с мелкими записями). Для машин с малым объёмом памяти рекомендуется ставить 8.

Тестирование

.venv/bin/python tests/test_mcp_e2e.py

Этот скрипт подключается к серверу через stdio как настоящий MCP-клиент, перечисляет все инструменты и вызывает каждый по очереди (включая разбор китайских названий, индексы/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    论坛：讨论、公告新闻、热帖、评论

Примечания

• Все данные получены из публичных API Xueqiu, котировки могут задерживаться, это не является инвестиционной рекомендацией.

• Проект предназначен только для обучения и исследований. Соблюдайте условия использования Xueqiu, избегайте высокочастотных запросов.

• API Xueqiu — не официальная открытая платформа; поля и доступность могут меняться в любой момент.