雪球 MCP Server

雪球の行情・財務・資金・コミュニティフォーラムのデータを、MCP 対応の任意のクライアント（Claude Code、Claude Desktop、Cherry Studio など）に接続します。

A 株 / 香港株 / 米国株に加え、指数・ETF・転換社債をカバー。全 22 個のツールを提供します。

特徴

• 大規模言語モデル向けの出力：雪球の生 API は ncf_from_oa、1.7205417189091E11 のようなフィールド名や数値を返します。本プロジェクトは 600 以上の財務フィールドを中国語に翻訳し、金額を「億元 / 万元」に換算し、複数期の財務諸表を「指標 × 報告期」の Markdown テーブルに転置します。モデルがそのまま読解でき、トークン消費も生 JSON よりはるかに少なくなります。

• 香港株フィールドは検証済み：雪球の香港株財務諸表は tto、plobtx、ploashh のような高度に省略されたコードを使用します。本プロジェクトの中英マッピングは、テンセント・ホールディングスの実際の財務数値を使い、会計恒等式による逆検証（例：tto - slgcost == gp、ta - tlia == teqy、nocf + ninvcf + nfcgcf == icdccceq）を行ったものであり、推測によるものではありません。

• フォーラム利用可能：コミュニティ API は xueqiu.com メインドメインではリスク管理にブロックされますが、本プロジェクトは雪球アプリが使用する api.xueqiu.com を経由するため、ログイン不要で個別銘柄のディスカッション、公告・ニュース、人気スレッド、コメントを読むことができます。スレッド本文の HTML はプレーンテキストにクリーニングされます。

• 設定不要：匿名トークンの自動取得と更新を行い、インストール後すぐに使用可能。Cookie も登録も不要です。

• スクリーニング指標のリアルタイム同期：スクリーナーの指標リストは雪球公式メタデータ API を直接読み取るため、雪球が指標を調整しても本プロジェクトが古くなることはありません。

• 小型マシンでも並列処理に耐える：階層型 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 の 1 項目のみを追加・変更します。既存の他の 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 に分割しないでください。

ツール一覧

検索と行情

財務

会社情報

資金面

市場とスクリーニング

コミュニティフォーラム

コードの書き方

中国語の名称を直接渡すこともできます（例：「贵州茅台」）。ツールが先に検索してからデータを取得します。

使用例

モデルに直接こう伝えます：

• 「茅台の最近の財務指標はどう？」

• 「PER 20 倍以下、配当利回り 3% 以上、時価総額 1000 億以上の A 株をスクリーニングして」

• 「雪球でみんなが宁德时代をどう議論しているか見て」

• 「贵州茅台と五粮液の直近 3 年の粗利率と ROE を比較して」

• 「テンセントに今日何か公告ある？」

スクリーナーのフィルタ構文：

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

つまり PER 0〜20 倍、配当利回り 3% 以上、時価総額 1000 億以上。境界値は空欄にして「制限なし」にできます。 指標名は list_screener_metrics で照会可能。_l サフィックスは最新の報告期を取得することを意味します。

オプション：独自の Cookie を設定

ほとんどの機能は匿名で使用可能です。ログイン状態が必要な一部の API（ユーザープロフィール詳細など）では、環境変数を設定できます：

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

MCP 設定では次のように記述します：

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

サーバーへのデプロイ

デフォルトでは stdio で起動し、1 プロセスは 1 クライアントのみにサービスを提供します。1 台のマシンで複数人・複数クライアントに同時にサービスを提供するには、 streamable-http に切り替えます：

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

クライアントは http://<アドレス>:8000/mcp に接続します。このモードはデフォルトで stateless です。サーバーはクライアントのセッションを保持せず、 メモリは接続数に応じて蓄積されず、複数レプリカでの水平スケーリングも容易です。

雪球 API には公式のオープンプラットフォームがありません。公網に公開する前に必ず認証とレート制限を追加し、他人のリクエスト量を雪球に転嫁しないでください。

性能と並列処理

すべてのリソースパラメータは環境変数で引き下げることができ、メモリの小さいマシンに適応します：

キャッシュはエンドポイントごとに階層化：行情 3 秒、K 線 30 秒、財務諸表 1 時間、会社情報 6 時間、 業界分類とスクリーニング指標 24 時間。同じデータへの並行リクエストは 1 つだけ上流に送信し、残りはその結果を待ちます。

実測結果

以下の数値は実環境での測定結果です（実際の雪球 API にアクセス、A 株取引時間帯、合計約 1,500 リクエスト）：

ボトルネックは本プロジェクトではありません：stock.xueqiu.com の単一リクエスト中央値 40.4 ms、api.xueqiu.com（コミュニティ系）84.8 ms、 一方で本プロジェクト自体はわずか 4.4 ms です。

主な効果はキャッシュとリクエストマージによるもので、次に HTTP/2 のコールド接続バースト時のマルチプレクシングです。 純粋なパイプラインスループット（キャッシュ無効化）は最適化前とほぼ同等です。これで高速化を期待しないでください。

tests/bench.py はローカルのモック上流を対象にしています（モック基準であり、実際の性能を表すものではありません）。 用途はパフォーマンスの宣伝ではなく回帰検出です：

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

判読のポイント：上流リクエスト数とピーク並列数が期待どおりかを確認します。QPS 数値はモックサーバー自体の スケジューリングオーバーヘッドの影響を大きく受け、ローカルループバック上で並列数が増えると 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 に接続し、全ツールを列挙して 1 つずつ実呼び出しします （中国語名の解決、指数/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 から取得しており、行情に遅延がある場合があります。いかなる投資アドバイスも構成しません。

• 本プロジェクトは学習・研究用のみです。雪球の利用規約を遵守し、高頻度リクエストは避けてください。

• 雪球 API は非公式のオープンプラットフォームであり、フィールドと可用性は随時変更される可能性があります。