Xueqiu MCP Server

Bring Xueqiu market quotes, financials, capital flow, and community forum data into any MCP-compatible client (Claude Code, Claude Desktop, Cherry Studio, etc.).

Covers A-shares / Hong Kong stocks / US stocks, plus indices, ETFs, and convertible bonds. 22 tools in total.

Features

• LLM-oriented output: Xueqiu's raw API returns fields and values like ncf_from_oa, 1.7205417189091E11. This project translates 600+ financial fields into Chinese, converts amounts into "hundred million yuan / ten thousand yuan", and transposes multi-period financial reports into "metric × reporting period" Markdown tables that models can read directly, with far lower token consumption than the raw JSON.

• Hong Kong stock fields validated: Xueqiu's HK stock financial reports use highly abbreviated codes like tto, plobtx, ploashh. The Chinese mappings in this project were reverse-confirmed using Tencent Holdings' actual financial figures and accounting identities (e.g., tto - slgcost == gp, ta - tlia == teqy, nocf + ninvcf + nfcgcf == icdccceq), not guessed.

• Forum works: The community API is blocked by risk control on the xueqiu.com main domain. This project uses api.xueqiu.com (used by the Xueqiu app) and can read stock discussions, announcements/news, hot posts, and comments without login. Post body HTML is cleaned into plain text.

• Zero configuration: Anonymous tokens are fetched and renewed automatically. Ready to use after installation — no Cookie, no registration needed.

• Screener metrics synced in real time: The screener's metric list is read directly from Xueqiu's official metadata API, so this project won't go stale when Xueqiu adjusts its metrics.

• Handles concurrency on small machines: Tiered TTL cache + concurrent request coalescing + HTTP/2 multiplexing. In real-world testing, repeated queries are 15.8x faster, requests to Xueqiu drop by 90%, and resident memory is about 75MB. See Performance & Concurrency.

Related MCP server: AgentSkills MCP

Installation

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

If you want 2~3x faster parsing of large JSON (e.g., 500 K-line bars), you can install with orjson:

uv pip install -e ".[fast]"

Connecting to Claude Code

Run this in the project directory:

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

Connecting to Claude Desktop / Other Clients

On macOS you can run the install script directly. It automatically waits for Claude to fully quit (a running Claude will overwrite the file with its in-memory config), backs up the original config, and only adds or modifies the xueqiu entry without touching your other existing MCP servers:

./install-claude-desktop.sh

To configure manually, edit the config file (Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json), and replace command with the absolute path of .venv/bin/xueqiu-mcp:

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

If the project path contains spaces or Chinese characters, be sure to use the full absolute path string — don't split it into args.

Tool Overview

Search & Quotes

Financials

Company Profile

Capital Flow

Market & Screening

Community Forum

Code Formats

You can also pass Chinese names directly (e.g., "贵州茅台"); the tool will search first, then fetch data.

Usage Examples

Just tell the model:

• "What are Moutai's recent financial metrics?"

• "Screen A-shares with P/E below 20x, dividend yield above 3%, and market cap above 100 billion"

• "See what people on Xueqiu are saying about CATL"

• "Compare Kweichow Moutai and Wuliangye's gross margin and ROE over the past three years"

• "Any announcements from Tencent today?"

Screener filter syntax:

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

That means P/E 0~20x, dividend yield above 3%, market cap above 100 billion. Boundaries can be left blank for no limit. Metric names can be looked up with list_screener_metrics; the _l suffix means the latest reporting period.

Optional: Configure Your Own Cookie

Most features work anonymously. A few endpoints that require a logged-in session (e.g., user profile details) can be configured via environment variables:

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

In the MCP config, write it as:

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

Deploying to a Server

By default it starts over stdio, with one process serving one client. To serve many users and clients from a single machine, switch to streamable-http:

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

Clients connect to http://<address>:8000/mcp. This mode is stateless by default — the server keeps no session per client, memory doesn't grow with connection count, and it's easy to scale horizontally with multiple replicas.

Xueqiu's API has no official open platform. Add your own authentication and rate limiting before exposing it publicly, and don't offload other people's request volume onto Xueqiu.

Performance & Concurrency

All resource parameters can be lowered via environment variables to fit small-memory machines:

The cache is tiered by endpoint: quotes 3 seconds, K-line 30 seconds, financials 1 hour, company profile 6 hours, industry classification and screener metrics 24 hours. When concurrent requests hit the same data, only one request goes out and the rest wait for its result.

Real-World Measurements

The numbers below come from real-world testing (hitting the real Xueqiu API during A-share trading hours, ~1,500 requests total):

The bottleneck is not this project: stock.xueqiu.com has a median of 40.4 ms per request, api.xueqiu.com (community) 84.8 ms, while this project itself accounts for only 4.4 ms.

The gains come mainly from caching and request coalescing, followed by HTTP/2 multiplexing during cold-connection bursts. Pure pipeline throughput (cache disabled) is roughly on par with before optimization — don't expect it to get faster from that.

tests/bench.py hits a local mock upstream (mock numbers, not representative of real performance), its purpose is regression detection rather than performance claims:

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

How to read the results: focus on whether upstream request count and peak concurrency match expectations. The QPS figure is heavily affected by the mock server's own scheduling overhead; QPS dropping as concurrency rises on the local loopback is an artifact of the test environment, not a problem with the code under test.

The cache layer has another set of zero-network regression tests covering request coalescing, cancellation propagation, LRU eviction, and byte accounting:

.venv/bin/python tests/test_cache.py

Known Limitations

• The concurrency gate is not a rate limiter. It only constrains "in-flight requests", not requests per unit time. Based on measured latency, 32 concurrent connections theoretically allows ~700 req/s toward Xueqiu. Please control your own pacing on the calling side.

• Real-world testing only validated up to 32 concurrent connections; there's no real data for higher concurrency.

• XUEQIU_CACHE_MB is an optimistic estimate; measured real memory growth is about 1.2~1.9x that value (higher for small-entry scenarios). For small-memory machines, 8 is recommended.

Testing

.venv/bin/python tests/test_mcp_e2e.py

This script connects to the server over stdio as a real MCP client, lists all tools and calls each one live (including Chinese-name resolution, indices/ETFs/convertible bonds, and error messages for various parameter validations), then prints the pass count.

Project Structure

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    论坛：讨论、公告新闻、热帖、评论

Notes

• All data comes from Xueqiu's public APIs; quotes may be delayed and do not constitute investment advice.

• This project is for learning and research only. Please comply with Xueqiu's terms of service and avoid high-frequency requests.

• Xueqiu's API is not an official open platform; fields and availability may change at any time.