Futu MCP

Uma plataforma de análise quantitativa para a Futu Securities, oferecendo cache inteligente, análise técnica e reconhecimento de padrões.

GitHub

Experimente este MCPPatrocinado

Documentação

Serviço Aprimorado Futu MCP 🚀

Plataforma profissional de análise quantitativa da Futu Securities baseada em FastAPI e Model Context Protocol (MCP), integrando cache inteligente, análise técnica, reconhecimento de padrões e outros recursos, elevando um simples proxy de API a um serviço de dados financeiros de nível empresarial.

🎯 A evolução perfeita de proxy de API para plataforma de análise quantitativa

🚀 Guia de início rápido em 5 minutos

📋 Checklist antes de iniciar

Componentes obrigatórios ✅

Python 3.10+ instalado
Futu OpenD iniciado e conectado
Conta Futu com permissões de cotações correspondentes

Componentes opcionais ⚪

Serviço Redis (melhora o desempenho do cache)
Biblioteca TA-Lib (melhora o desempenho computacional)

⚡ Início com um clique

# 1. 克隆项目
git clone <your-repo-url>
cd mcp_futu

# 2. 创建并激活虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

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

# 4. 启动服务（四种方式）
# 🌟 智能统一入口（推荐）- 菜单式操作，提供建议和响应
python futu_assistant.py

# 🚀 智能重启 - 自动停止旧服务并启动新服务
python restart.py

# 🔥 手动启动增强版MCP服务 - 端口8001
python main_enhanced.py

# 🎯 简化版HTTP服务（稳定）- 端口8002  
python main_enhanced_simple_alternative.py

# 5. (可选) 启动独立 MCP 包装服务 - 端口9001
#  Web 服务和 MCP 工具彻底解耦，MCP 只负责转发到 Web API
WEB_API_BASE_URL=http://localhost:8001 MCP_PORT=9001 python mcp_service/main.py

🌟 Entrada unificada inteligente (altamente recomendado)

Assistente inteligente que resolve todas as necessidades em um só lugar:

# 启动智能助手
python futu_assistant.py

# 功能菜单：
# 1️⃣ 启动服务    - 智能重启富途服务
# 2️⃣ 健康检查    - 检查服务状态和连接  
# 3️⃣ 测试功能    - 完整功能测试
# 4️⃣ 股票报价    - 获取实时股票报价
# 5️⃣ 技术分析    - 计算技术指标
# 6️⃣ 缓存状态    - 查看缓存系统状态
# 7️⃣ API文档     - 打开API文档
# 8️⃣ 查看日志    - 检查服务运行日志
# 9️⃣ 故障诊断    - 智能故障诊断
# 0️⃣ 退出       - 退出助手

# 特点：
# 🧠 智能建议和自动响应
# 🔧 故障自动诊断和解决方案
# 📊 实时状态监控
# 🎯 一键解决各种问题

🔄 Reinicialização inteligente

Se encontrar problemas de porta em uso (Address already in use), use o script de reinicialização inteligente:

# 一键重启 - 自动检测并停止已有服务
python restart.py

# 功能特点：
# ✅ 自动检测端口占用
# ✅ 安全停止已有进程  
# ✅ 重新启动增强版服务
# ✅ 验证启动成功
# ✅ 显示服务地址和文档链接

🔍 Verificação de inicialização

# 健康检查
curl http://localhost:8001/health

# 预期输出:
# {"status":"healthy","futu_connected":true,"cache_available":true}

Se você vir a saída acima, parabéns, você iniciou com sucesso! 🎉

🔗 Instruções de implantação independente do serviço MCP

A Web API (cotações, Dashboard, /api/**) continua sendo fornecida pelo main_enhanced.py, mantendo a porta 8001.
As ferramentas MCP agora são executadas de forma independente pelo mcp_service/main.py:

WEB_API_BASE_URL=http://localhost:8001 MCP_PORT=9001 python mcp_service/main.py

O .env lê o EXTERNAL_MCP_ENDPOINT (padrão http://localhost:9001/mcp). Se você alterar a porta MCP ou a forma de implantação, atualize essa variável para que o serviço Web forneça o endereço correto no /mcp/status ou no redirecionamento.
Ao acessar o http://localhost:8001/mcp, você receberá um redirecionamento 307 para o MCP externo, facilitando a migração de configurações antigas; recomendamos atualizar o endereço para a nova porta no cliente MCP o quanto antes.

🌟 Destaques principais

🔥 Sistema de cache inteligente

Arquitetura de cache em três camadas: memória + Redis + SQLite em múltiplos níveis
Melhoria de desempenho de 99%+: velocidade de resposta 99,86% maior quando o cache é acessado
Política de expiração inteligente: gerenciamento de cache diferenciado por tipo de dado
Tolerância a falhas automática: degradação automática para cache local em caso de falha do Redis

📊 Análise técnica profissional

15+ indicadores técnicos: MACD, RSI, Bandas de Bollinger, KDJ, médias móveis, etc.
Reconhecimento inteligente de sinais: identificação automática de cruzamentos de ouro/morte, sobrecompra/sobrevenda e outros sinais de negociação
Implementação em Python puro: suporte a TA-Lib e Python puro
Otimização de cache: resultados de indicadores são armazenados em cache de forma inteligente, evitando recálculos

⚡ Otimização de desempenho

Redução de transferência de dados em 99%+: compressão inteligente de dados de candles e informações básicas
Otimização do tempo de resposta: tempo médio de resposta 3-5x maior
Gerenciamento de memória: alocação inteligente de memória e coleta de lixo
Reutilização de conexões: otimização do pool de conexões da API Futu

🛡️ Recursos de nível empresarial

Monitoramento de saúde: monitoramento completo do serviço e do status do cache
Recuperação de erros: mecanismos automáticos de nova tentativa e degradação graciosa
Extensibilidade: design modular para facilitar a expansão de funcionalidades
Compatibilidade reversa: totalmente compatível com a API original

📊 Comparação de desempenho

Métrica	Serviço original	Serviço aprimorado	Melhoria
Tempo de resposta para candles	0,069s	0,0001s (cache acessado)	99,86% ⬆️
Volume de dados transferidos	1092KB	8,4KB	99,2% ⬇️
Suporte a indicadores técnicos	❌ Não	✅ 15+	Novo ✨
Sistema de cache	❌ Não	✅ Arquitetura em três camadas	Novo ✨
Análise inteligente	❌ Não	✅ Quantitativa profissional	Novo ✨

💻 Guia de uso das funcionalidades principais

🔍 1. Consulta de cotações de ações

# 单个股票查询
curl -X POST http://localhost:8001/api/quote/stock_quote \
  -H "Content-Type: application/json" \
  -d '{"code_list": ["HK.00700"]}'

# 批量股票查询（推荐）
curl -X POST http://localhost:8001/api/quote/stock_quote \
  -H "Content-Type: application/json" \
  -d '{
    "code_list": ["HK.00700", "HK.09660", "HK.00005"],
    "optimization": {"only_essential_fields": true}
  }'

Exemplo de resposta:

{
  "ret_code": 0,
  "ret_msg": "获取股票报价成功",
  "data": {
    "quotes": [{
      "code": "HK.00700",
      "last_price": 325.4,
      "change_val": 2.8,
      "change_rate": 0.87,
      "volume": 12345678,
      "turnover": 4.01e9
    }]
  }
}

📈 2. Dados históricos de candles

# 获取日K线数据
curl -X POST http://localhost:8001/api/quote/history_kline \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "ktype": "K_DAY",
    "start": "2024-01-01",
    "end": "2024-12-31",
    "max_count": 100
  }'

# 获取分钟级K线数据
curl -X POST http://localhost:8001/api/quote/history_kline \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "ktype": "K_30M",
    "max_count": 48
  }'

Tipos de candles suportados:

K_1M, K_3M, K_5M, K_15M, K_30M, K_60M (linhas de minutos)
K_DAY (diário), K_WEEK (semanal), K_MON (mensal)

🧮 3. Análise de indicadores técnicos

# 计算单个指标
curl -X POST http://localhost:8001/api/analysis/technical_indicators \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "indicators": ["rsi"],
    "ktype": "K_DAY",
    "period": 30
  }'

# 计算多个指标
curl -X POST http://localhost:8001/api/analysis/technical_indicators \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "indicators": ["macd", "rsi", "bollinger_bands"],
    "ktype": "K_DAY"
  }'

# 计算所有指标（完整分析）
curl -X POST http://localhost:8001/api/analysis/technical_indicators \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "indicators": ["all"],
    "ktype": "K_DAY"
  }'

Indicadores técnicos suportados:

Indicadores de tendência: macd, moving_averages, ema
Indicadores de momentum: rsi, kdj
Indicadores de volatilidade: bollinger_bands, atr
Indicadores de volume: obv, vwap
Indicadores de força: adx

🧠 4. Snapshot de análise abrangente (recomendado para MCP/Agentes)

curl -X POST http://localhost:8001/api/analysis/snapshot \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "include_history": true,
    "include_technicals": true,
    "technical_period": 120
  }' | jq '.'

Destaques da interface

Uma única requisição fornece cotações, análise técnica, fluxo de capital, estratégias mais recentes, sinais fundamentais e visão geral de posições
O campo insights fornece automaticamente estatísticas multidimensionais (como número de sinais positivos/negativos, quantidade de estratégias, preço mais recente)
É possível filtrar módulos como candles históricos, fluxo de capital e indicadores técnicos por meio de parâmetros
A ferramenta MCP get_analysis_snapshot reutiliza diretamente essa interface, eliminando a necessidade de encadear múltiplas interfaces

🗄️ 5. Gerenciamento de cache

# 查看缓存状态
curl http://localhost:8001/api/cache/status

# 预加载热门股票数据
curl -X POST http://localhost:8001/api/cache/preload \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["HK.00700", "HK.09660", "HK.00005"],
    "days": 30,
    "ktypes": ["K_DAY", "K_30M"]
  }'

# 清理缓存
curl -X DELETE http://localhost:8001/api/cache/clear \
  -H "Content-Type: application/json" \
  -d '{"cache_type": "memory"}'

📝 6. Registro e revisão de recomendações de estratégia

# 保存一条策略建议
curl -X POST http://localhost:8001/api/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "action": "BUY",
    "rationale": "突破年线并放量，RSI回升至50上方",
    "confidence": 0.72,
    "timeframe": "swing",
    "tags": ["技术面", "突破"],
    "source": "kimi-k2-thinking-turbo",
    "evidence": [
      {"type": "indicator", "name": "MACD", "value": "金叉"},
      {"type": "news", "title": "Q3 财报高于预期"}
    ]
  }'

# 查询策略建议（可按代码、标签、采纳状态等过滤）
curl -X POST http://localhost:8001/api/recommendations/query \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HK.00700",
    "tag": "技术面",
    "limit": 20
  }'

A interface registra automaticamente de forma persistente no data/recommendations.db, podendo ser usada via HTTP e também apresentada no cliente MCP como ferramentas save_recommendation / get_recommendations, facilitando a escrita e consulta de recomendações de estratégia por modelos de linguagem.

📺 6. Painel de visualização em tempo real (Web)

Quando você deseja exibir cotações, notícias, estratégias e posições pessoais de uma ação para colegas ou usuários finais, pode gerar um painel Web compartilhável para qualquer ativo por meio da nova interface create_dashboard_session:

# 1) 生成会话，得到 Web URL
curl -X POST http://localhost:8001/api/dashboard/session \
  -H "Content-Type: application/json" \
  -d '{"code": "HK.00700"}'

# 响应示例：
# {
#   "session_id": "1Np4dJ6xG6M",
#   "url": "http://localhost:8001/web/dashboard?session=1Np4dJ6xG6M"
# }

# 2) 把 url 发给浏览器或 MCP 客户端，页面会自动：
#    • 订阅 Futu 报价/盘口/逐笔/分时等推送，并实时刷新图表
#    • 拉取 Metaso 搜索结果，按“利好/利空”分区展示
#    • 展示资金流向 / 资金分布 / 历史K线等关键指标
#    • 读取最近的策略建议和（若可用）个人持仓摘要
#    • 会话 ID 会落盘到 `data/dashboard_sessions.json`，重启服务后仍可复用链接

# ⚙️ 如需让 MCP 返回公网地址，可设置 `DASHBOARD_BASE_URL` 环境变量：
# export DASHBOARD_BASE_URL="https://your-domain.com"
# 这样 `create_dashboard_session` 工具会直接返回公网可访问的 URL。

看板页面顶部会展示所有已订阅的股票，并实时显示 Futu 订阅额度使用情况，可一键取消订阅，便于控制配额。

> 另外，服务启动后控制台会输出 `http://localhost:8001/web`，打开即可查看所有看板的列表总览，并快速进入详情页。

No lado MCP, a ferramenta create_dashboard_session também será exposta; o LLM só precisa fornecer o código da ação para obter o link do painel em tempo real, permitindo o fluxo de trabalho "pergunte e receba a URL".

🔧 Detalhes de configuração do ambiente

1. Configuração do ambiente Python

# 确认Python版本
python --version  # 需要 3.10+

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements_enhanced.txt

2. Configuração do Futu OpenD

# 1. 下载富途OpenD客户端
# https://www.futunn.com/download/openAPI

# 2. 启动OpenD
# - 登录富途账号
# - 确保有相应市场的行情权限
# - 默认端口: 11111

# 3. 验证连接
telnet 127.0.0.1 11111

3. Configuração do Redis (opcional, recomendado)

# macOS安装
brew install redis
brew services start redis

# Ubuntu安装
sudo apt-get install redis-server
sudo systemctl start redis

# 验证Redis
redis-cli ping  # 应返回 PONG

4. Configuração do TA-Lib (opcional, melhoria de desempenho)

# macOS安装
brew install ta-lib
pip install TA-Lib

# Ubuntu安装
sudo apt-get install libta-lib-dev
pip install TA-Lib

# 注意: 如果安装失败，系统会自动使用纯Python实现

🤖 Guia de integração com assistentes de IA

Opção 0: Entrada unificada inteligente (recomendado para novos usuários)

A forma mais simples de uso, sem necessidade de programação:

# 🌟 启动智能助手 - 一站式解决所有需求
python futu_assistant.py

# 智能助手提供：
# 🎯 菜单式操作界面
# 🧠 智能建议和自动响应  
# 🔧 故障自动诊断
# 📊 实时状态监控
# 🚀 一键重启和修复
# 💡 使用指导和帮助

Características:

✅ Zero conhecimento de programação: operação por menu, simples e fácil
✅ Diagnóstico inteligente: detecção automática de problemas e fornecimento de soluções
✅ Correção com um clique: tratamento automático de porta em uso, reinicialização de serviços, etc.
✅ Monitoramento em tempo real: exibe status do serviço, situação do cache, status da conexão
✅ Interação amigável: fornece respostas sugeridas e orienta o usuário

Opção 1: API HTTP estável (recomendado para integração de desenvolvimento)

Use diretamente a API HTTP, 100% estável e confiável:

import httpx
import asyncio

class FutuAnalysisAPI:
    def __init__(self, base_url="http://localhost:8001"):
        self.base_url = base_url
        self.client = httpx.AsyncClient()
    
    async def get_stock_quote(self, codes: list):
        """获取股票报价"""
        response = await self.client.post(
            f"{self.base_url}/api/quote/stock_quote",
            json={"code_list": codes}
        )
        return response.json()
    
    async def get_technical_analysis(self, code: str, indicators: list = ["all"]):
        """获取技术分析"""
        response = await self.client.post(
            f"{self.base_url}/api/analysis/technical_indicators",
            json={
                "code": code,
                "indicators": indicators,
                "ktype": "K_DAY"
            }
        )
        return response.json()

# 使用示例
api = FutuAnalysisAPI()
quote = await api.get_stock_quote(["HK.00700"])
analysis = await api.get_technical_analysis("HK.00700")

Opção 2: Integração via protocolo MCP

Adicione o servidor MCP nas configurações do Cursor:

{
  "mcpServers": {
    "futu-enhanced": {
      "url": "http://127.0.0.1:8001/mcp",
      "name": "富途量化分析平台"
    }
  }
}

Observação: o protocolo MCP pode apresentar problemas de temporização na inicialização; recomendamos priorizar o uso da API HTTP.

📚 Referência completa da API

🔍 Interfaces de dados de mercado

Nome da interface	Endpoint	Método	Descrição	Cache
Cotação de ações	`/api/quote/stock_quote`	POST	Informações de cotações em tempo real	10 segundos
Candles históricos	`/api/quote/history_kline`	POST	Dados históricos de candles	Permanente
Informações básicas da ação	`/api/quote/stock_basicinfo`	POST	Lista de informações básicas de ações	1 dia

🧮 Interfaces de análise técnica

Nome da interface	Endpoint	Método	Indicadores suportados	Cache
Análise de indicadores técnicos	`/api/analysis/technical_indicators`	POST	Todos os 15+ indicadores	5 minutos
Indicador MACD	`/api/analysis/macd`	POST	Análise especializada de MACD	5 minutos
Indicador RSI	`/api/analysis/rsi`	POST	Análise especializada de RSI	5 minutos

🗄️ Interfaces de gerenciamento

Nome da interface	Endpoint	Método	Descrição
Verificação de saúde	`/health`	GET	Status de saúde do serviço
Status do cache	`/api/cache/status`	GET	Visualizar uso do cache
Pré-carregamento de dados	`/api/cache/preload`	POST	Pré-carregamento em lote de dados
Limpeza de cache	`/api/cache/clear`	DELETE	Limpar dados de cache
Documentação da API	`/docs`	GET	Documentação Swagger da API

🚨 Guia de solução de problemas

❌ Problemas comuns e soluções

Problema 1: Falha de conexão com a Futu

ERROR: 连接富途OpenD失败

Etapas de solução:

# 1. 检查OpenD是否运行
netstat -an | grep 11111

# 2. 检查账号登录状态
# 确保OpenD客户端已登录并有行情权限

# 3. 重启服务
python main_enhanced.py

Problema 2: Erro de cache

WARNING: Redis连接失败，使用本地缓存

Solução:

# Redis可选，不影响核心功能
# 如需启用Redis:
brew install redis && brew services start redis  # macOS
# 或
sudo apt-get install redis-server && sudo systemctl start redis  # Ubuntu

Problema 3: Falha no cálculo de indicadores técnicos

ERROR: 技术分析异常: index out of bounds

Solução:

# 清理缓存，重新获取数据
curl -X DELETE http://localhost:8001/api/cache/clear \
  -H "Content-Type: application/json" \
  -d '{"cache_type": "sqlite"}'

# 预加载数据
curl -X POST http://localhost:8001/api/cache/preload \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["HK.00700"], "days": 60}'

Problema 4: Chamada MCP cancelada

ERROR: Received request before initialization was complete

Solução:

# 使用稳定的HTTP API替代MCP
curl -X POST http://localhost:8001/api/quote/stock_quote \
  -H "Content-Type: application/json" \
  -d '{"code_list": ["HK.00700"]}'

🔍 Comandos de verificação de saúde

# 1. 服务状态检查
curl http://localhost:8001/health

# 2. 缓存状态检查
curl http://localhost:8001/api/cache/status

# 3. 测试核心功能
curl -X POST http://localhost:8001/api/quote/stock_quote \
  -H "Content-Type: application/json" \
  -d '{"code_list": ["HK.00700"]}'

# 4. 性能测试
time curl -X POST http://localhost:8001/api/analysis/technical_indicators \
  -H "Content-Type: application/json" \
  -d '{"code": "HK.00700", "indicators": ["rsi"]}'

📊 Métricas de desempenho esperadas

Métrica	Primeira requisição	Cache acessado	Meta
Cotação de ações	< 200ms	< 10ms	✅
Dados de candles	< 500ms	< 1ms	✅
Indicadores técnicos	< 300ms	< 50ms	✅
Verificação de saúde	< 10ms	-	✅

📦 Implantação em produção

Implantação com Docker (recomendado)

FROM python:3.10-slim

WORKDIR /app
COPY requirements_enhanced.txt .
RUN pip install -r requirements_enhanced.txt

COPY . .
EXPOSE 8001

CMD ["uvicorn", "main_enhanced:app", "--host", "0.0.0.0", "--port", "8001"]

# 构建并运行
docker build -t futu-mcp-enhanced .
docker run -d -p 8001:8001 \
  -v $(pwd)/data:/app/data \
  --name futu-mcp \
  futu-mcp-enhanced

Implantação como serviço Systemd

# /etc/systemd/system/futu-mcp.service
[Unit]
Description=富途MCP增强服务
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/mcp_futu
Environment=PATH=/opt/mcp_futu/venv/bin
ExecStart=/opt/mcp_futu/venv/bin/python main_enhanced.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

# 启用服务
sudo systemctl enable futu-mcp
sudo systemctl start futu-mcp
sudo systemctl status futu-mcp

🔮 Comparação de versões e seleção

Guia de seleção de versão do serviço

Versão	Porta	Recursos	Cenário de uso	Estabilidade
main_enhanced.py	8001	Protocolo duplo MCP + HTTP	Integração com assistentes de IA	95% ⚠️
main_enhanced_simple_alternative.py	8002	API HTTP pura	Ambiente de produção	100% ✅
main_simple.py	8000	Funcionalidades básicas	Uso leve	100% ✅

Recomendação de seleção:

🔥 Ambiente de produção: main_enhanced_simple_alternative.py (porta 8002)
🤖 Integração com IA: main_enhanced.py (porta 8001) + API HTTP como alternativa
⚡ Cenário leve: main_simple.py (porta 8000)

🤝 Obtenha suporte

Autoatendimento

📖 Documentação da API: http://localhost:8001/docs
🔍 Verificação de saúde: http://localhost:8001/health
📊 Status do cache: http://localhost:8001/api/cache/status

Suporte da comunidade

GitHub Issues: Relatar problema
Discussões: GitHub Discussions

Diagnóstico rápido

Ao encontrar problemas, forneça as seguintes informações:

# 1. 系统信息
python --version
pip list | grep -E "(fastapi|futu|redis|pandas)"

# 2. 服务状态
curl http://localhost:8001/health

# 3. 错误日志
tail -n 50 logs/futu_mcp.log  # 如果有日志文件

📜 Licença

Este projeto é licenciado sob a licença MIT - consulte o arquivo LICENSE

🎉 Comece sua jornada profissional em negociação quantitativa!

🔥 De proxy de API a plataforma de análise quantitativa | Desempenho 99%+ maior | Estabilidade de nível empresarial