Xueqiu MCP Server

雪球(Xueqiu)의 시세·재무·자금 및 커뮤니티 포럼 데이터를 MCP를 지원하는 모든 클라이언트(Claude Code, Claude Desktop, Cherry Studio 등)에 연결합니다.

A주 / 홍콩주 / 미국주를 지원하며, 지수·ETF·전환사채까지 포함합니다. 총 22개 도구를 제공합니다.

특징

• LLM 친화적 출력: Xueqiu 원본 API는 ncf_from_oa, 1.7205417189091E11 같은 필드명과 숫자를 반환합니다. 이 프로젝트는 600개 이상의 재무 필드를 한국어로 번역하고, 금액을「억 위안 / 만 위안」단위로 환산하며, 여러 기간의 재무제표를「지표 × 보고 기간」형식의 Markdown 테이블로 전치합니다. 모델이 바로 이해할 수 있고, 토큰 소비도 원본 JSON보다 훨씬 적습니다.

• 홍콩주 필드 검증 완료: Xueqiu 홍콩주 재무제표는 tto, plobtx, ploashh 같은 고도로 축약된 코드를 사용합니다. 이 프로젝트의 중국어 매핑은 Tencent Holdings의 실제 재무제표 수치를 회계 항등식으로 역검증한 것입니다(예: tto - slgcost == gp, ta - tlia == teqy, nocf + ninvcf + nfcgcf == icdccceq). 추측이 아닙니다.

• 포럼 사용 가능: 커뮤니티 API는 xueqiu.com 메인 도메인에서 리스크 관리에 차단되지만, 이 프로젝트는 Xueqiu 앱이 사용하는 api.xueqiu.com을 경유하므로 로그인 없이 개별 종목 토론, 공지·뉴스, 인기 게시물, 댓글을 읽을 수 있습니다. 게시물 본문의 HTML은 순수 텍스트로 정제됩니다.

• 설정 불필요: 익명 토큰을 자동으로 획득하고 갱신하므로 설치 후 바로 사용 가능합니다. Cookie도, 회원가입도 필요 없습니다.

• 종목 선별 지표 실시간 동기화: 종목 선별기의 지표 목록을 Xueqiu 공식 메타데이터 API에서 직접 읽으므로, Xueqiu가 지표를 조정해도 이 프로젝트가 구식이 되지 않습니다.

• 소형 머신에서도 동시성 처리 가능: 계층형 TTL 캐시 + 동시 요청 병합 + HTTP/2 멀티플렉싱. 실제 환경 측정 결과 반복 조회가 15.8배 빨라지고 Xueqiu로 가는 요청이 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는 메모리 설정으로 해당 파일을 덮어씀), 기존 설정을 백업하며, 기존의 다른 MCP는 건드리지 않고 xueqiu 항목만 추가/수정합니다:

./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% 이상, 시가총액 1,000억 위안 이상인 A주 골라줘」

• 「Xueqiu에서 사람들이 CATL(닝더스다이)을 어떻게 논의하는지 봐줘」

• 「귀주마오타이와 우량예 최근 3년 매출총이익률과 ROE 비교해줘」

• 「텐센트 오늘 공지 있나?」

종목 선별기 필터 문법:

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

즉 PER 0~20배, 배당수익률 3% 이상, 시가총액 1,000억 위안 이상입니다. 경계값을 비워두면 제한 없음을 의미합니다. 지표명은 list_screener_metrics로 조회할 수 있으며, _l 접미사는 최신 보고 기간을 의미합니다.

선택 사항: 자체 Cookie 설정

대부분의 기능은 익명으로 사용 가능합니다. 로그인 상태가 필요한 일부 API(예: 사용자 프로필 상세)는 환경 변수로 설정할 수 있습니다:

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입니다 — 서버가 클라이언트 세션을 유지하지 않으므로 메모리가 연결 수에 따라 누적되지 않고, 다중 복제본으로 수평 확장하기도 쉽습니다.

Xueqiu API는 공식 개방 플랫폼이 없으므로, 공개 네트워크에 노출하기 전에 반드시 인증과 속도 제한을 직접 추가하고, 타인의 요청량을 Xueqiu에 전가하지 마세요.

성능 및 동시성

모든 리소스 파라미터는 환경 변수로 낮출 수 있어 소형 메모리 머신에 적합합니다:

캐시는 endpoint별로 계층화됩니다: 시세 3초, K라인 30초, 재무제표 1시간, 기업 정보 6시간, 업종 분류 및 종목 선별 지표 24시간. 동일한 데이터에 대한 동시 요청은 하나만 외부로 보내고 나머지는 그 결과를 기다립니다.

실측 결과

다음 수치는 실제 환경에서 측정한 것입니다(실제 Xueqiu API 호출, 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를 Xueqiu에 보낼 수 있습니다. 호출 측에서 직접 속도를 조절하세요.

• 실제 환경 검증은 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    论坛：讨论、公告新闻、热帖、评论

설명

• 데이터는 모두 Xueqiu 공개 API에서 가져오며, 시세는 지연될 수 있습니다. 어떠한 투자 조언도 구성하지 않습니다.

• 이 프로젝트는 학습·연구용이며, Xueqiu의 서비스 약관을 준수하고 고빈도 요청을 피하세요.

• Xueqiu API는 비공식 개방 플랫폼이므로 필드와 가용성은 언제든 변경될 수 있습니다.