Servidor MCP de Xueqiu

Conecta los datos de cotizaciones, finanzas, flujos de capital y el foro comunitario de Xueqiu a cualquier cliente compatible con MCP (Claude Code, Claude Desktop, Cherry Studio, etc.).

Cubre acciones A / acciones de Hong Kong / acciones de EE. UU., además de índices, ETF y bonos convertibles. En total, 22 herramientas.

Características

• Salida orientada a modelos de lenguaje: la API original de Xueqiu devuelve campos y valores como ncf_from_oa, 1.7205417189091E11. Este proyecto traduce más de 600 campos financieros al chino, convierte los importes a «cientos de millones / diez miles de yuanes» y reorganiza los estados financieros de varios periodos en tablas Markdown de «indicador × periodo de reporte». El modelo puede leerlos directamente y el consumo de tokens es mucho menor que con el JSON original.

• Campos de Hong Kong verificados: los informes financieros de Hong Kong de Xueqiu usan códigos muy abreviados como tto, plobtx, ploashh. El mapeo al chino de este proyecto se confirmó de forma inversa usando los valores financieros reales de Tencent Holdings y las identidades contables (por ejemplo, tto - slgcost == gp, ta - tlia == teqy, nocf + ninvcf + nfcgcf == icdccceq), no se basa en suposiciones.

• Foro utilizable: la interfaz comunitaria está bloqueada por el control de riesgos en el dominio principal xueqiu.com. Este proyecto usa api.xueqiu.com, que emplea la app de Xueqiu, y no requiere inicio de sesión para leer discusiones de acciones individuales, anuncios y noticias, publicaciones populares y comentarios. El HTML del cuerpo de las publicaciones se limpia y convierte a texto plano.

• Sin configuración: el token anónimo se obtiene y renueva automáticamente. Funciona nada más instalarlo, sin necesidad de cookies ni registro.

• Indicadores de selección de acciones sincronizados en tiempo real: la lista de indicadores del screener se lee directamente de la interfaz de metadatos oficial de Xueqiu; si Xueqiu ajusta los indicadores, este proyecto no queda desactualizado.

• Capaz de soportar concurrencia en máquinas pequeñas: caché TTL por niveles + fusión de solicitudes concurrentes + multiplexación HTTP/2. En pruebas de entorno real, las consultas repetidas son 15,8 veces más rápidas, las solicitudes a Xueqiu se reducen un 90 % y la memoria residente es de unos 75 MB. Ver Rendimiento y concurrencia.

Related MCP server: AgentSkills MCP

Instalación

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

Si quieres que el análisis de JSON grandes (como 500 velas K) sea 2~3 veces más rápido, puedes incluir orjson:

uv pip install -e ".[fast]"

Conexión con Claude Code

En el directorio del proyecto, ejecuta:

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

Conexión con Claude Desktop / otros clientes

En macOS puedes ejecutar directamente el script de instalación. Espera automáticamente a que Claude se cierre por completo (un Claude en ejecución sobrescribiría el archivo con su configuración en memoria), hace una copia de seguridad de la configuración original y solo añade o modifica la entrada xueqiu, sin tocar los demás MCP que ya tengas:

./install-claude-desktop.sh

Para configuración manual, edita el archivo de configuración (en Claude Desktop está en ~/Library/Application Support/Claude/claude_desktop_config.json), y sustituye command por la ruta absoluta de .venv/bin/xueqiu-mcp:

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

Si la ruta del proyecto contiene espacios o caracteres chinos, usa obligatoriamente la cadena de ruta absoluta completa; no la dividas en args.

Resumen de herramientas

Búsqueda y cotizaciones

Finanzas

Información de la empresa

Flujo de capital

Mercado y selección de acciones

Foro comunitario

Formato de los códigos

También puedes pasar directamente el nombre en chino (por ejemplo, «贵州茅台»); la herramienta primero buscará y luego obtendrá los datos.

Ejemplos de uso

Dile directamente al modelo:

• «¿Cómo están los indicadores financieros recientes de Moutai?»

• «Ayúdame a filtrar acciones A con PER inferior a 20 veces, rentabilidad por dividendo superior al 3 % y capitalización superior a 100 000 millones»

• «Mira cómo discute la gente en Xueqiu sobre CATL»

• «Compara el margen bruto y el ROE de los últimos tres años entre Kweichow Moutai y Wuliangye»

• «¿Tencent tiene algún anuncio hoy?»

La sintaxis de filtrado del screener:

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

Es decir, PER de 0~20 veces, rentabilidad por dividendo superior al 3 % y capitalización superior a 100 000 millones. Los límites pueden dejarse vacíos para indicar «sin límite». Los nombres de los indicadores pueden consultarse con list_screener_metrics; el sufijo _l indica que se toma el último periodo de reporte.

Opcional: configurar tu propia cookie

La gran mayoría de funciones funcionan de forma anónima. Las pocas interfaces que requieren sesión iniciada (como el detalle del perfil de usuario) pueden configurarse con una variable de entorno:

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

En la configuración de MCP se escribe así:

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

Despliegue en un servidor

Por defecto se inicia con stdio, y un proceso solo atiende a un cliente. Para atender a varias personas y varios clientes a la vez en una misma máquina, cambia a streamable-http:

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

El cliente se conecta a http://<dirección>:8000/mcp. Este modo es stateless por defecto: el servidor no mantiene sesiones para los clientes, la memoria no se acumula con el número de conexiones y también facilita la escalabilidad horizontal con varias réplicas.

La interfaz de Xueqiu no tiene una plataforma abierta oficial. Antes de exponerla a Internet, añade tu propia autenticación y limitación de velocidad, y no traslades el volumen de solicitudes de otros a Xueqiu.

Rendimiento y concurrencia

Todos los parámetros de recursos pueden reducirse con variables de entorno para adaptarse a máquinas con poca memoria:

La caché se divide por niveles según el endpoint: cotizaciones 3 segundos, velas K 30 segundos, informes financieros 1 hora, información de empresa 6 horas, clasificación sectorial e indicadores del screener 24 horas. Cuando hay solicitudes concurrentes por los mismos datos, solo se envía una y el resto espera su resultado.

Mediciones reales

Las siguientes cifras provienen de pruebas en entorno real (llamando a las interfaces reales de Xueqiu, en horario de negociación de acciones A, con unas 1 500 solicitudes en total):

El cuello de botella no está en este proyecto: stock.xueqiu.com tiene una mediana de 40,4 ms por solicitud, api.xueqiu.com (comunidad) 84,8 ms, mientras que este proyecto solo representa 4,4 ms.

El beneficio principal proviene de la caché y la fusión de solicitudes, y en segundo lugar de la multiplexación HTTP/2 en ráfagas con conexiones frías. El rendimiento puro de tubería (con la caché desactivada) es prácticamente igual que antes de la optimización: no esperes que sea más rápido gracias a ello.

tests/bench.py usa un upstream mock local (criterio mock, no equivale al rendimiento real); su propósito es la detección de regresiones, no presumir de rendimiento:

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

Claves de interpretación: presta atención a si el número de solicitudes ascendentes y el pico de concurrencia coinciden con lo esperado. El número de QPS se ve muy afectado por la sobrecarga de programación del propio mock server; en el bucle local, la caída de QPS al aumentar la concurrencia es un artefacto del entorno de pruebas, no indica un problema en el código probado.

La capa de caché tiene además un conjunto de pruebas de regresión sin red, que cubren fusión de solicitudes, propagación de cancelación, expulsión LRU y contabilidad de bytes:

.venv/bin/python tests/test_cache.py

Límites conocidos

• La compuerta de concurrencia no es un limitador de velocidad. Solo restringe el «número de solicitudes en tránsito», no el número de solicitudes por unidad de tiempo. Según la latencia medida, 32 de concurrencia permiten teóricamente unas 700 req/s hacia Xueqiu. Controla el ritmo desde el lado de la llamada.

• El entorno real solo se ha verificado hasta 32 de concurrencia; no hay datos reales para concurrencias más altas.

• XUEQIU_CACHE_MB es una estimación algo optimista; en la práctica, el crecimiento real de memoria es de aproximadamente 1,2~1,9 veces ese valor (más alto en el caso de entradas pequeñas). En máquinas con poca memoria se recomienda poner 8.

Pruebas

.venv/bin/python tests/test_mcp_e2e.py

Este script se conecta a este servidor a través de stdio como un cliente MCP real, lista todas las herramientas y las invoca una a una (incluida la resolución de nombres en chino, índices/ETF/bonos convertibles, y los mensajes de error de validación de varios parámetros) y finalmente imprime el número de pruebas superadas.

Estructura del proyecto

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

Notas

• Todos los datos provienen de las interfaces públicas de Xueqiu; las cotizaciones pueden tener retraso y no constituyen ningún consejo de inversión.

• Este proyecto es solo para estudio e investigación. Respeta los términos de servicio de Xueqiu y evita solicitudes de alta frecuencia.

• La interfaz de Xueqiu no es una plataforma abierta oficial; los campos y la disponibilidad pueden ajustarse en cualquier momento.