Tushare MCP

Tushare MCP 📈

Extensão de assistente de IA para dados financeiros do mercado de ações A, construída sobre o protocolo MCP (Model Context Protocol) (v0.1.0)

---

Tushare MCP é uma ponte que conecta IA (Claude, Cursor) aos grandes dados financeiros do Tushare. Ele implementa o padrão Model Context Protocol (MCP), permitindo que seu assistente de IA chame diretamente mais de 30 interfaces profissionais de dados financeiros, consultando em tempo real cotações de ações, demonstrações financeiras, fundamentos de empresas e outros dados essenciais.

Este projeto utiliza o SDK tinyshare, mais conveniente e acessível, em substituição à biblioteca oficial tushare. Utilize as seguintes dependências:

import tinyshare as ts

---

Se você não sabe como usar, leia o documento do Tencent abaixo: Instruções de uso do Tushare MCP

Se você quiser usar diretamente adicionando o mcp server, ignorando o processo trabalhoso, entre em contato comigo para testar: WeChat: Buuzzy0603

---

Endpoint de teste, experimente gratuitamente as ferramentas mcp, sem necessidade de token

Se você não sabe como usar, envie os dois endereços abaixo para a IA e peça para ela adicionar o mcp server

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

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

---

20/02/2025 Complemento das interfaces de ETF e fundos de investimento

Esta atualização focou em complementar as interfaces de fundos públicos e ETF. Além disso, para atender à forte tendência dos grandes modelos (especialmente em cenários de comparação e análise de dados) de consultas com "múltiplos códigos separados por vírgula", que a API subjacente do Tushare não suporta nativamente, implantamos um "processador local de divisão e mesclagem de solicitações" em todos os módulos de Fund. Esse mecanismo intercepta inteligentemente listas separadas por vírgulas, realiza múltiplas solicitações atômicas em segundo plano e concatena os dataframes resultantes.

16/02/2025 Refatoração

Esta iteração implementou a refatoração de um script de arquivo único para uma engenharia modular. Dividimos o server.py monolítico original em uma arquitetura de três camadas: server.py (responsável apenas pela orquestração de serviços e roteamento), tools/ (núcleo lógico dividido por domínio de negócio) e utils/ (infraestrutura). Essa mudança desacoplou completamente a inicialização do serviço da lógica de negócio, dando a cada interface do Tushare (como cotações, finanças) um espaço de arquivo independente, melhorando significativamente a manutenibilidade e extensibilidade do código, estabelecendo uma base sólida de engenharia para a integração futura de mais fontes de dados e colaboração em equipe.

🌟 Recursos principais

1. 🤖 Compatibilidade perfeita com os principais clientes de IA

• Claude Desktop: Suporte aos modos padrão Streamable HTTP / Stdio, execução local direta.
• Cursor IDE: Consulte dados de ações relacionados a código diretamente no editor, auxiliando na programação financeira.

2. 📊 Cobertura completa de dados

• Dados básicos: Lista de ações, IPOs, calendário de dias de negociação, fundamentos de empresas listadas.
• Dados de mercado: Cotações diárias/semanais/mensais, indicadores diários (PE/PB/valor de mercado), análise de limites de alta/baixa.
• Demonstrações financeiras: Demonstração de resultados, balanço patrimonial, demonstração de fluxo de caixa, previsões de desempenho, composição do negócio principal.
• Fundos e ETFs: Listas de fundos negociados em bolsa/fora de bolsa, cotações diárias e participações, currículos de gestores de fundos, carteiras de fundos, dividendos e valores patrimoniais líquidos, fatores técnicos profissionais.
• Dados especiais: Top 10 ações negociadas via Shanghai-Hong Kong/Shenzhen-Hong Kong Stock Connect, financiamento de margem e empréstimo de ações, penhor de ações.

3. 🛠 Gerenciamento inteligente de Token & API

• Configuração em um clique: Fornece a ferramenta setup_tushare_token, configure diretamente pelo chat.
• Criptografia local: Token armazenado com segurança no ambiente local, sem necessidade de inserção repetida.
• Reescrita de consultas em lote: Para interfaces de fundos que não suportam consultas em lote ts_code no Tushare, implementa automaticamente localmente "divisão por vírgula -> solicitações em loop -> concatenação de dados", adaptando-se perfeitamente ao hábito de consultas em lote dos LLMs.

4. ⚡ Arquitetura de alto desempenho

• Streamable HTTP: Baseado no protocolo de transporte Streamable HTTP nativo do SDK MCP, substituindo o antigo SSE.
• Tinyshare SDK: Encapsulamento profundamente otimizado da interface Tushare, com suporte a retry e tratamento de exceções.

🏗️ Arquitetura 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

🚀 Início rápido

1. Preparação do ambiente

Certifique-se de ter o python 3.10+ instalado.

# 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. Configuração

Você também pode configurar manualmente por meio de variáveis de ambiente:

# 创建配置文件
touch .env

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

3. Iniciar o serviço

Opção A: Servidor HTTP (modo Streamable HTTP) - Recomendado

Adequado para clientes que suportam MCP remoto, como o Cursor.

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

Opção B: Modo Stdio

Adequado para integração local com Claude Desktop.

python server.py --stdio

🔌 Conexão do cliente

Configuração no Cursor

1. Abra Cursor Settings -> Features -> MCP
2. Clique em "+ Add New MCP Server"
3. Preencha as informações:
   • Name: tushare
   • Type: Streamable HTTP
   • URL: http://localhost:8000/mcp

Configuração no Claude Desktop

Edite o arquivo de configuração ~/Library/Application Support/Claude/claude_desktop_config.json:

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

🧰 Lista de ferramentas

📈 Básico e mercado (Stock)

Ferramenta	Descrição
get_stock_basic	Obtém a lista de informações básicas de ações A (código, nome, data de listagem, etc.)
get_trade_cal	Obtém o calendário de dias de negociação das principais bolsas
get_stock_company	Obtém informações básicas de empresas listadas (capital registrado, representante legal, descrição)
get_namechange	Histórico de alterações de nomes
get_stk_managers	Principais membros da administração de empresas listadas
daily	Cotações diárias de ações/índices A (abertura, máxima, mínima, fechamento, volume), suporta múltiplos códigos separados por vírgula
weekly / monthly	Cotações semanais / mensais de ações/índices, suporta múltiplos códigos separados por vírgula
get_daily_basic	Indicadores diários (taxa de rotatividade, relação de volume, PE, PB, valor de mercado total)
get_suspend_d	Informações diárias de suspensão/retomada de negociação
get_hsgt_top10	Top 10 ações negociadas via Shanghai/Shenzhen-Hong Kong Stock Connect

💰 Dados financeiros (Finance)

Ferramenta	Descrição
get_income_statement	Demonstração de resultados
get_balance_sheet	Balanço patrimonial
get_cash_flow	Demonstração de fluxo de caixa
get_forecast	Previsão de desempenho
get_express	Relatório rápido de desempenho
get_fina_indicator	Dados de indicadores financeiros (EPS, ROE, margem bruta, etc.)
get_fina_mainbz	Composição do negócio principal
get_disclosure_date	Datas planejadas de divulgação de relatórios financeiros

📈 Fundos e ETFs (Fund)

Ferramenta	Descrição
etf_basic	Lista de informações básicas de ETFs domésticos
etf_index	Índice ao qual o ETF pertence ou que rastreia
etf_share_size	Participações e tamanho diários do ETF
fund_basic	Lista de dados de fundos públicos (negociados em bolsa + fora de bolsa)
fund_company	Diretório de gestores de fundos públicos
fund_manager	Diretório e currículos de gestores de fundos públicos
fund_share	Histórico de tamanho e participações de fundos públicos
fund_daily	Cotações diárias de fundos negociados em bolsa/ETF
fund_adj	Fator de ajuste de preços de fundos
fund_nav	Histórico de valor patrimonial líquido de fundos públicos
fund_div	Registros de dividendos de fundos públicos
fund_portfolio	Dados de carteira de fundos públicos (top 10 ações)
fund_factor_pro	Dados de fatores técnicos de fundos negociados em bolsa (MACD/RSI, etc.)
stk_mins	Cotações históricas de ações em minutos (5/15/30/60 minutos; 1 minuto não disponível)

🌍 Mercado global: Ações de Hong Kong e EUA (Global)

Ferramenta	Descrição
hk_daily / hk_weekly / hk_monthly	Cotações diárias/semanais/mensais de ações de Hong Kong (código de 5 dígitos, ex.: 00700; ajuste opcional)
us_daily / us_weekly / us_monthly	Cotações diárias/semanais/mensais de ações dos EUA (ticker, ex.: AAPL; ajuste opcional)
global_index_daily	Gráfico de velas de índices globais (HSI / Hang Seng Tech / China Enterprises / Dow Jones / S&P 500 / Nasdaq 100 / Nasdaq Composite)
hk_fina_indicator	Principais indicadores financeiros de ações de Hong Kong (EPS/ROE/margem bruta/crescimento anual de receita e lucro líquido, anual ou por período de relatório)
us_fina_indicator	Principais indicadores financeiros de ações dos EUA (crescimento de receita/lucro líquido, margem bruta/ROE/índice de liquidez imediata, etc., relatório anual ou trimestral)
hk_income / hk_balancesheet / hk_cashflow	Três demonstrações financeiras de ações de Hong Kong (valores por conta, linhas por período de relatório)
us_income / us_balancesheet / us_cashflow	Três demonstrações financeiras de ações dos EUA (valores por conta, linhas por período de relatório)
us_filings	Documentos de registro SEC de ações dos EUA (10-K/10-Q/8-K, etc., com links para os originais)
hk_announcements	Anúncios de ações de Hong Kong (dados oficiais do HKEXnews, com links em PDF)
search_symbol	Consulta cruzada de código/nome de ações de Hong Kong e EUA (consulte primeiro se não tiver certeza do código)

Para a lista completa de ferramentas, consulte o diretório tools/ ou acesse a documentação da API após iniciar o serviço.

📁 Estrutura do projeto

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           # 项目文档

📄 Licença

MIT

---