xueqiu-mcp

An MCP server for Xueqiu (Snowball) that exposes community posts, stock quotes, watchlists, portfolios, and market news to AI assistants through standard Model Context Protocol tools.

It is designed for Claude Desktop, Cursor, Codex, QoderWork, and other MCP-compatible clients that can launch stdio servers.

This project relies on publicly reachable Xueqiu endpoints and an optional user cookie token. API availability, permissions, and response shapes may change without notice.

Highlights

Related MCP server: Xueqiu MCP

Use Cases

• Track recent posts, long-form articles, and discussions from Xueqiu users or market KOLs.

• Query real-time quotes and valuation metrics for A-shares, Hong Kong stocks, and US stocks.

• Inspect your own watchlists or public watchlists from other Xueqiu users.

• Pull Xueqiu hot discussions, news feeds, and 7x24 live updates into AI workflows.

• Combine stock screening, industry data, and company profiles for research workflows.

Installation

Requirements

• Node.js 20 or later

• npm

• An MCP client that supports stdio servers

Build Locally

git clone <repo-url>
cd xueqiu-mcp
npm install
npm run build

The compiled server entrypoint is dist/index.js.

Authentication

Login state is resolved in this order:

1. XUEQIU_TOKEN environment variable (a bare xq_a_token value or a full cookie string)

2. A local cookie file written by npm run login

3. An in-memory anonymous token (public endpoints only)

One-time login (recommended)

npm run login opens your installed Google Chrome. Sign in once with the QR code or SMS code, and the login cookie is saved locally. The server picks it up automatically on startup — no environment variable needed and no browser download.

npm run login

It reuses your installed Chrome, so nothing extra is downloaded. If Chrome is missing, either install it or fall back to Playwright's bundled Chromium (a ~150 MB one-time download):

npx playwright install chromium

The cookie is stored at ~/.config/xueqiu-mcp/cookies.json (%USERPROFILE%\.config\xueqiu-mcp\cookies.json on Windows). When it expires, run npm run login again.

Manual token

You can still copy the cookie by hand:

1. Log in to Xueqiu.

2. Open Developer Tools → Application / Storage → Cookies for https://xueqiu.com.

3. Copy xq_a_token. Login-only endpoints usually also need u, so copying xq_a_token=...; u=... together is safest.

Claude Desktop / Cursor / QoderWork

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "xueqiu-mcp": {
      "command": "node",
      "args": ["/path/to/xueqiu-mcp/dist/index.js"]
    }
  }
}

If you already ran npm run login, no env block is needed. To override the saved cookie, add "env": { "XUEQIU_TOKEN": "your value" }.

Codex CLI

Add the server to ~/.codex/config.toml:

[mcp_servers.xueqiu-mcp]
command = "node"
args = ["/path/to/xueqiu-mcp/dist/index.js"]

If you already ran npm run login, no env block is needed. To override the saved cookie, add env = { XUEQIU_TOKEN = "your value" }.

Restart your MCP client after saving the configuration.

Tools

Community and KOL Tracking

get_hot_posts.scope supports day, week, and month. get_news_feed.category supports headline, a_stock, us_stock, hk_stock, fund, and live.

Stock Market Data

Symbol examples: SH600519, SZ000001, 00700, AAPL.

Watchlist Viewing (read-only)

Common system folder IDs include -1 for all stocks, -5 for A-shares, -6 for US stocks, and -7 for Hong Kong stocks; -110 for all funds, -17 for funds, and -16 for private funds. Prefer IDs returned by get_watchlists or get_user_watchlists.

Watchlist Editing (write)

These write tools require a valid login (npm run login or XUEQIU_TOKEN). Items are added to or removed from the default folder of each kind; the server routes by symbol prefix (SH/SZ stocks, F/P funds, ZH cubes).

Portfolio Tracking

Examples

Show me the latest posts from this Xueqiu user.

Search for Xueqiu users who discuss new energy stocks.

What is in user 2292705444's public watchlist?

Get the current quote, PE, PB, and dividend yield for SH600519.

Compare quotes for SH600519, SZ300750, and AAPL.

What are the hottest A-share stocks today?

Show current holdings for portfolio ZH2001629.

Show the latest Xueqiu 7x24 live news.

Development

npm run dev      # Start from TypeScript source with tsx
npm run build    # Compile TypeScript to dist/
npm start        # Start the compiled MCP server

Architecture

xueqiu-mcp/
├── src/
│   ├── index.ts          # MCP server entrypoint, tool registration, and response formatting
│   ├── xueqiu-api.ts     # Xueqiu API client, token handling, and HTTP helpers
│   ├── login.ts          # One-time browser login helper
│   ├── login-cookie.ts   # Login-state validation and Cookie serialization
│   └── cookie-store.ts   # Local Cookie persistence
├── test/                 # Login and API regression tests
├── dist/                 # Compiled output
├── package.json          # Package metadata and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md

The implementation intentionally keeps the runtime small:

• Node.js / ESM / ES2022

• TypeScript

• @modelcontextprotocol/sdk

• Playwright (login helper)

• zod

Data, Permissions, and Safety

• XUEQIU_TOKEN is read from the environment and should not be committed to source control.

• Anonymous tokens are fetched only when needed and are kept in memory.

• Login-required tools fail fast when neither a valid local Cookie nor XUEQIU_TOKEN is available.

• Visibility of other users' watchlists, portfolios, and profiles depends on their privacy settings and Xueqiu's API permissions.

• Xueqiu may change endpoints, fields, rate limits, or access policies at any time.

• Requests are throttled (default ~1–1.5 s between requests, jittered) and retried with exponential backoff for transient 429/5xx/network errors only. 401/403/400 are never auto-retried. After 5 consecutive transient failures the client opens a 5-minute circuit breaker. Set XUEQIU_MIN_INTERVAL_MS to override the throttle interval (0 disables it).

• Use reasonable request rates and respect Xueqiu's terms of service.

Disclaimer

This project is for personal learning, research, and automation assistance only. It is not investment advice, trading advice, or a recommendation to buy or sell securities. This project is not affiliated with, endorsed by, or officially authorized by Xueqiu or Beijing Xueqiu Information Technology Co., Ltd. Users are responsible for complying with Xueqiu's terms, platform rules, and applicable laws. All consequences arising from use of this project are the user's responsibility.

License

MIT