Tushare MCP

Tushare MCP 📈

Extensión de asistente de IA para datos financieros del mercado A, construida sobre el protocolo MCP (Model Context Protocol) (v0.1.0)

---

Tushare MCP es un puente que conecta la IA (Claude, Cursor) con los macrodatos financieros de Tushare. Implementa el estándar Model Context Protocol (MCP), permitiendo que tu asistente de IA llame directamente a más de 30 interfaces profesionales de datos financieros para consultar en tiempo real cotizaciones de acciones, estados financieros, fundamentos de empresas y otros datos clave.

Este proyecto utiliza el SDK de tinyshare, más conveniente y económico, en lugar de la biblioteca oficial de tushare. Usa las siguientes dependencias:

import tinyshare as ts

---

Si no sabes cómo usarlo, consulta el siguiente documento de Tencent: Instrucciones de uso de Tushare MCP

Si deseas usarlo directamente agregando un servidor MCP y evitar el proceso tedioso, puedes contactarme para una prueba: WeChat: Buuzzy0603

---

Punto de conexión de prueba: puedes probar las herramientas MCP gratis, sin necesidad de token

Si no sabes cómo usarlo, envía las siguientes dos direcciones a la IA y pídele que agregue el servidor MCP

### stock endpoint
https://stock-mcp.pricetrade.top/sse

### fund endpoint
https://fund-mcp.pricetrade.top/sse

---

2025.02.20 Se completaron las interfaces de ETF y fondos de herramientas

Esta actualización se centró en completar las interfaces de fondos públicos y ETF. Además, ante la fuerte tendencia de los grandes modelos (especialmente en escenarios de comparación y análisis de datos) a realizar consultas con múltiples códigos separados por comas, mientras que la API subyacente de Tushare no lo soporta de forma nativa, hemos incorporado un "procesador local de división y fusión de solicitudes" en la capa inferior de todos los módulos de Fund. Este mecanismo intercepta de forma inteligente las listas separadas por comas, realiza múltiples solicitudes atómicas en segundo plano y concatena los marcos de datos resultantes.

2025.02.16 Reestructuración

Esta iteración logró la reestructuración de un script de archivo único a un proyecto modular. Dividimos el server.py monolítico original en una arquitectura de tres capas: server.py (solo responsable de la orquestación y el enrutamiento de servicios), tools/ (núcleo lógico dividido por dominio de negocio) y utils/ (infraestructura). Este cambio desacopló por completo el inicio del servicio de la lógica de negocio, permitiendo que cada interfaz de Tushare (como cotizaciones, finanzas) tenga su propio espacio de archivo independiente, lo que mejora significativamente la mantenibilidad y extensibilidad del código, sentando una base sólida de ingeniería para la futura integración de más fuentes de datos y la colaboración en equipo.

🌟 Funciones principales

1. 🤖 Adaptación perfecta a los principales clientes de IA

• Claude Desktop: soporte de modo estándar Streamable HTTP / Stdio, ejecución local directa.
• Cursor IDE: consulta directamente datos bursátiles relacionados con el código en el editor, asistencia en programación financiera.

2. 📊 Cobertura de datos en todas las dimensiones

• Datos básicos: lista de acciones, nuevas acciones IPO, calendario de días de negociación, fundamentos de empresas cotizadas.
• Datos de cotizaciones: cotizaciones diarias/semanales/mensuales, indicadores diarios (PE/PB/capitalización de mercado), análisis de límites de subida/bajada.
• Estados financieros: cuenta de resultados, balance general, estado de flujos de efectivo, avisos de resultados, composición del negocio principal.
• Fondos y ETF: listas de fondos dentro/fuera de bolsa, cotizaciones y participaciones diarias, currículums de gestores de fondos, tenencias de fondos, dividendos y valor liquidativo de fondos, factores técnicos profesionales.
• Datos especiales: diez valores más negociados de Shanghai-Hong Kong Stock Connect, financiación de valores, prenda de acciones.

3. 🛠 Gestión inteligente de tokens y API

• Configuración con un clic: proporciona la herramienta setup_tushare_token, configuración completada mediante conversación.
• Cifrado local: el token se almacena de forma segura en el entorno local, sin necesidad de ingresarlo repetidamente.
• Reescritura de consultas por lotes: para las interfaces de fondos que no admiten consultas por lotes con ts_code en Tushare, se implementa automáticamente a nivel local "división por comas -> solicitudes en bucle -> concatenación de datos", adaptándose perfectamente al hábito de consultas por lotes de los LLM.

4. ⚡ Arquitectura de alto rendimiento

• Streamable HTTP: basado en el protocolo de transporte Streamable HTTP nativo del SDK de MCP, reemplazando el antiguo SSE.
• Tinyshare SDK: encapsulación profundamente optimizada de la interfaz de Tushare, con soporte de reintentos y manejo de excepciones.

🏗️ Arquitectura técnica

graph TD
    Client(["AI Client (Claude / Cursor)"]) -->|MCP Protocol (Streamable HTTP / Stdio)| MCPServer[Tushare MCP Server]
    MCPServer -->|Tool Execution| Tools[Tool Implementation]
    Tools -->|Data Request| SDK[Tinyshare SDK]
    SDK -->|HTTP API| Tushare[("Tushare Pro API")]
    Tushare -->|JSON Data| SDK
    SDK -->|Structured Result| Tools
    Tools -->|Context| MCPServer
    MCPServer -->|Answer| Client

🚀 Inicio rápido

1. Preparación del entorno

Asegúrate de tener instalado Python 3.10+.

# 1. 克隆项目
git clone <repository-url> tushare_mcp
cd tushare_mcp

# 2. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# 3. 安装依赖
pip install -r requirements.txt

2. Configuración

También puedes configurar manualmente mediante variables de entorno:

# 创建配置文件
touch .env

# 写入 Token（推荐使用 MCP 工具 setup_tushare_token 自动配置）
echo "TUSHARE_TOKEN=你的token" >> .env

3. Iniciar el servicio

Opción A: Servidor HTTP (modo Streamable HTTP) - Recomendado

Adecuado para clientes que admiten MCP remoto, como Cursor.

python server.py
# 服务将运行在 http://localhost:8000
# MCP 端点: http://localhost:8000/mcp

Opción B: Modo Stdio

Adecuado para la integración local con Claude Desktop.

python server.py --stdio

🔌 Conexión de clientes

Configuración en Cursor

1. Abre Cursor Settings -> Features -> MCP
2. Haz clic en "+ Add New MCP Server"
3. Completa la información:
   • Name: tushare
   • Type: Streamable HTTP
   • URL: http://localhost:8000/mcp

Configuración en Claude Desktop

Edita el archivo de configuración ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tushare": {
      "command": "/绝对路径/至/你的/venv/bin/python",
      "args": [
        "/绝对路径/至/你的/tushare_mcp/server.py",
        "--stdio"
      ]
    }
  }
}

🧰 Lista de herramientas

📈 Datos básicos y de cotizaciones (Stock)

Herramienta	Descripción
get_stock_basic	Obtiene la lista de información básica de acciones A (código, nombre, fecha de cotización, etc.)
get_trade_cal	Obtiene el calendario de días de negociación de las principales bolsas
get_stock_company	Obtiene la información básica de empresas cotizadas (capital registrado, representante legal, descripción)
get_namechange	Historial de cambios de nombre
get_stk_managers	Principales miembros de la dirección de empresas cotizadas
daily	Cotizaciones diarias de acciones/índices A (apertura, máximo, mínimo, cierre, volumen), admite múltiples códigos separados por comas
weekly / monthly	Cotizaciones semanales / mensuales de acciones/índices, admite múltiples códigos separados por comas
get_daily_basic	Indicadores diarios (tasa de rotación, relación de volumen, PE, PB, capitalización total)
get_suspend_d	Información diaria de suspensión/reanudación de cotización
get_hsgt_top10	Diez valores más negociados de Shanghai-Hong Kong Stock Connect

💰 Datos financieros (Finance)

Herramienta	Descripción
get_income_statement	Cuenta de resultados
get_balance_sheet	Balance general
get_cash_flow	Estado de flujos de efectivo
get_forecast	Avisos de resultados
get_express	Informes rápidos de resultados
get_fina_indicator	Datos de indicadores financieros (EPS, ROE, margen bruto, etc.)
get_fina_mainbz	Composición del negocio principal
get_disclosure_date	Fechas planificadas de publicación de informes financieros

📈 Fondos y ETF (Fund)

Herramienta	Descripción
etf_basic	Lista de información básica de ETF nacionales
etf_index	Índice al que pertenece o que sigue el ETF
etf_share_size	Participaciones y escala diarias del ETF
fund_basic	Lista de datos de fondos públicos (dentro + fuera de bolsa)
fund_company	Directorio de gestores de fondos públicos
fund_manager	Directorio y currículums de gestores de fondos públicos
fund_share	Historial de escala y participaciones de fondos públicos
fund_daily	Cotizaciones diarias de fondos/ETF dentro de bolsa
fund_adj	Factores de ajuste de fondos
fund_nav	Historial de valor liquidativo de fondos públicos
fund_div	Registros de dividendos de fondos públicos
fund_portfolio	Datos de tenencias de fondos públicos (diez principales valores)
fund_factor_pro	Datos de factores técnicos de fondos dentro de bolsa (MACD/RSI, etc.)
stk_mins	Cotizaciones históricas por minutos de acciones (5/15/30/60 minutos; 1 minuto no disponible)

🌍 Mercados globales: Hong Kong y EE. UU. (Global)

Herramienta	Descripción
hk_daily / hk_weekly / hk_monthly	Cotizaciones diarias/semanales/mensuales de acciones de Hong Kong (códigos de 5 dígitos, como 00700; ajuste opcional)
us_daily / us_weekly / us_monthly	Cotizaciones diarias/semanales/mensuales de acciones de EE. UU. (ticker, como AAPL; ajuste opcional)
global_index_daily	Velas de índices globales (HSI / Hang Seng Tech / China Enterprises / Dow Jones / S&P 500 / Nasdaq 100 / Nasdaq Composite)
hk_fina_indicator	Principales indicadores financieros de acciones de Hong Kong (EPS/ROE/margen bruto/crecimiento interanual de ingresos y beneficio neto, anual o por período de informe)
us_fina_indicator	Principales indicadores financieros de acciones de EE. UU. (crecimiento interanual de ingresos/beneficio neto/margen bruto/ROE/ratio rápido, informe anual o trimestral)
hk_income / hk_balancesheet / hk_cashflow	Tres estados financieros de acciones de Hong Kong (montos por partida, filas por período de informe)
us_income / us_balancesheet / us_cashflow	Tres estados financieros de acciones de EE. UU. (montos por partida, filas por período de informe)
us_filings	Documentos de presentación SEC de acciones de EE. UU. (10-K/10-Q/8-K, etc., con enlaces al texto original)
hk_announcements	Anuncios de acciones de Hong Kong (datos oficiales de Disclosure Easy, con enlaces PDF)
search_symbol	Consulta cruzada de códigos/nombres de acciones de Hong Kong y EE. UU. (consulta primero si no estás seguro del código)

Para la lista completa de herramientas, consulta el directorio tools/ o accede a la documentación de la API después de iniciar el servicio.

📁 Estructura del proyecto

tushare_MCP/
├── api_docs/           # 原始 Tushare API 文档参考
├── mcp_test/           # MCP 工具测试记录
├── tools/              # MCP 工具实现核心代码
│   ├── finance/        # 财务类工具 (income, balance, cashflow...)
│   └── stock/
│       ├── basic/      # 基础数据工具 (stock_basic, trade_cal...)
│       └── quote/      # 行情数据工具 (daily, weekly, hsgt...)
├── utils/              # 通用工具函数 (logger, token_manager)
├── server.py           # MCP Server 入口 (FastAPI + FastMCP)
├── requirements.txt    # 项目依赖
└── README.md           # 项目文档

📄 Licencia

MIT

---