Futu MCP

Una plataforma de análisis cuantitativo para Futu Securities, que ofrece almacenamiento en caché inteligente, análisis técnico y reconocimiento de patrones.

GitHub

Prueba este MCPPatrocinado

Documentación

Futu MCP Servicio Mejorado 🚀

Plataforma de análisis cuantitativo profesional para Futu Securities basada en FastAPI y Model Context Protocol (MCP), que integra caché inteligente, análisis técnico, reconocimiento de patrones y otras funciones, elevando un simple proxy de API a un servicio de datos financieros de nivel empresarial.

🎯 La evolución perfecta de proxy de API a plataforma de análisis cuantitativo

🚀 Guía de inicio rápido en 5 minutos

📋 Lista de verificación antes de comenzar

Componentes requeridos ✅

Python 3.10+ instalado
Futu OpenD iniciado y con sesión iniciada
La cuenta de Futu tiene los permisos de cotización correspondientes

Componentes opcionales ⚪

Servicio Redis (mejora el rendimiento de caché)
Biblioteca TA-Lib (mejora el rendimiento de cálculo)

⚡ Inicio con un clic

# 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 (muy recomendado)

Asistente inteligente que resuelve todas las necesidades en un solo lugar:

# 启动智能助手
python futu_assistant.py

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

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

🔄 Función de reinicio inteligente

Si encuentra problemas de ocupación de puertos (Address already in use), use el script de reinicio inteligente:

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

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

🔍 Verificación de inicio

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

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

Si ve la salida anterior, ¡felicidades, se ha iniciado correctamente! 🎉

🔗 Notas sobre la implementación independiente del servicio MCP

La API web (cotizaciones, Dashboard, /api/**) sigue siendo proporcionada por main_enhanced.py, manteniendo el puerto 8001.
Las herramientas MCP ahora son ejecutadas de forma independiente por mcp_service/main.py:

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

.env leerá EXTERNAL_MCP_ENDPOINT (por defecto http://localhost:9001/mcp). Si modifica el puerto MCP o el método de implementación, actualice esta variable para que el servicio web proporcione la dirección correcta en /mcp/status o al redirigir.
Al acceder a http://localhost:8001/mcp recibirá una redirección 307 al MCP externo, lo que facilita la migración fluida de configuraciones antiguas; se recomienda cambiar la dirección al nuevo puerto en el cliente MCP lo antes posible.

🌟 Características principales

🔥 Sistema de caché inteligente

Arquitectura de caché de tres niveles: memoria + Redis + SQLite
Mejora de rendimiento del 99%+: velocidad de respuesta 99.86% más rápida con caché activa
Política de expiración inteligente: gestión de caché diferenciada por tipo de datos
Tolerancia a fallos automática: degradación automática a caché local cuando Redis falla

📊 Análisis técnico profesional

Más de 15 indicadores técnicos: MACD, RSI, Bandas de Bollinger, KDJ, medias móviles, etc.
Reconocimiento inteligente de señales: identificación automática de cruces dorados/muertos, sobrecompra/sobreventa y otras señales de trading
Implementación en Python puro: admite tanto TA-Lib como cálculo en Python puro
Optimización de caché: los resultados de indicadores se almacenan en caché inteligentemente para evitar cálculos repetidos

⚡ Optimización de rendimiento

Reducción de transferencia de datos del 99%+: compresión inteligente de datos de velas e información básica
Optimización del tiempo de respuesta: tiempo de respuesta promedio 3-5 veces más rápido
Gestión de memoria: asignación inteligente de memoria y recolección de basura
Reutilización de conexiones: optimización del pool de conexiones de la API de Futu

🛡️ Características de nivel empresarial

Monitoreo de salud: monitoreo completo del estado del servicio y la caché
Recuperación de errores: reintentos automáticos y mecanismos de degradación elegante
Extensibilidad: diseño modular para facilitar la expansión de funciones
Compatibilidad hacia atrás: totalmente compatible con la API original

📊 Comparación de rendimiento

Métrica de función	Servicio original	Servicio mejorado	Mejora
Tiempo de respuesta de velas	0.069s	0.0001s (caché activa)	99.86% ⬆️
Volumen de datos transferidos	1092KB	8.4KB	99.2% ⬇️
Soporte de indicadores técnicos	❌ No	✅ 15+	Nuevo ✨
Sistema de caché	❌ No	✅ Arquitectura de tres niveles	Nuevo ✨
Análisis inteligente	❌ No	✅ Cuantitativo profesional	Nuevo ✨

💻 Guía de uso de funciones principales

🔍 1. Consulta de cotizaciones de acciones

# 单个股票查询
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}
  }'

Ejemplo de respuesta:

{
  "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. Datos históricos de velas

# 获取日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 velas compatibles:

K_1M, K_3M, K_5M, K_15M, K_30M, K_60M (velas de minutos)
K_DAY (diarias), K_WEEK (semanales), K_MON (mensuales)

🧮 3. Análisis 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 compatibles:

Indicadores de tendencia: macd, moving_averages, ema
Indicadores de impulso: rsi, kdj
Indicadores de volatilidad: bollinger_bands, atr
Indicadores de volumen: obv, vwap
Indicadores de fuerza: adx

🧠 4. Instantánea de análisis integral (recomendado para MCP/Agent)

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 '.'

Aspectos destacados de la interfaz

Una sola solicitud obtiene cotizaciones, análisis técnico, flujo de fondos, estrategias más recientes, señales fundamentales y resumen de posiciones
El campo insights proporciona automáticamente estadísticas multidimensionales (como número de señales positivas/negativas, cantidad de estrategias, precio más reciente)
Se pueden recortar módulos como velas históricas, flujo de fondos e indicadores técnicos mediante parámetros
La herramienta MCP get_analysis_snapshot reutiliza directamente esta interfaz, evitando la necesidad de encadenar múltiples interfaces

🗄️ 5. Gestión de caché

# 查看缓存状态
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 y revisión de recomendaciones de estrategia

# 保存一条策略建议
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
  }'

La interfaz persistirá automáticamente los registros en data/recommendations.db, y se puede usar tanto a través de HTTP como en clientes MCP mediante las herramientas save_recommendation / get_recommendations, lo que facilita que los modelos de lenguaje grandes escriban y consulten recomendaciones de estrategia.

📺 6. Panel de visualización en tiempo real (Web)

Cuando desee mostrar las cotizaciones, noticias, estrategias y posiciones personales de una acción a colegas o usuarios finales, puede generar un panel web compartible para cualquier instrumento a través de la nueva interfaz 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`，打开即可查看所有看板的列表总览，并快速进入详情页。

En el lado MCP también se expone la herramienta create_dashboard_session; el LLM solo necesita proporcionar el código de la acción para obtener el enlace del panel en tiempo real, logrando un flujo de trabajo de "preguntar y obtener URL".

🔧 Configuración detallada del entorno

1. Configuración del entorno 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. Configuración de Futu OpenD

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

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

# 3. 验证连接
telnet 127.0.0.1 11111

3. Configuración de 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. Configuración de TA-Lib (opcional, mejora de rendimiento)

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

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

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

🤖 Guía de integración con asistentes de IA

Opción 0: Entrada unificada inteligente (recomendada para nuevos usuarios)

La forma más sencilla de uso, sin necesidad de programar:

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

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

Características:

✅ Sin conocimientos de programación: operación basada en menús, fácil de usar
✅ Diagnóstico inteligente: detección automática de problemas y soluciones
✅ Reparación con un clic: manejo automático de ocupación de puertos, reinicio de servicios, etc.
✅ Monitoreo en tiempo real: muestra estado del servicio, situación de caché, estado de conexión
✅ Interacción amigable: proporciona respuestas sugeridas y guía al usuario

Opción 1: API HTTP estable (recomendada para integración de desarrollo)

Use directamente la API HTTP, 100% estable y confiable:

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")

Opción 2: Integración mediante protocolo MCP

Agregue el servidor MCP en la configuración de Cursor:

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

Nota: El protocolo MCP puede tener problemas de sincronización de inicialización; se recomienda priorizar el uso de la API HTTP.

📚 Referencia completa de la API

🔍 Interfaces de datos de cotizaciones

Nombre de interfaz	Endpoint	Método	Descripción de función	Caché
Cotización de acciones	`/api/quote/stock_quote`	POST	Información de cotización en tiempo real	10 segundos
Velas históricas	`/api/quote/history_kline`	POST	Datos históricos de velas	Permanente
Información básica de acciones	`/api/quote/stock_basicinfo`	POST	Lista de información básica de acciones	1 día

🧮 Interfaces de análisis técnico

Nombre de interfaz	Endpoint	Método	Indicadores compatibles	Caché
Análisis de indicadores técnicos	`/api/analysis/technical_indicators`	POST	Todos los 15+ indicadores	5 minutos
Indicador MACD	`/api/analysis/macd`	POST	Análisis especializado MACD	5 minutos
Indicador RSI	`/api/analysis/rsi`	POST	Análisis especializado RSI	5 minutos

🗄️ Interfaces de administración

Nombre de interfaz	Endpoint	Método	Descripción de función
Verificación de salud	`/health`	GET	Estado de salud del servicio
Estado de caché	`/api/cache/status`	GET	Ver uso de caché
Precarga de datos	`/api/cache/preload`	POST	Precarga masiva de datos
Limpiar caché	`/api/cache/clear`	DELETE	Limpiar datos de caché
Documentación de API	`/docs`	GET	Documentación Swagger de la API

🚨 Guía de solución de problemas

❌ Problemas comunes y soluciones

Problema 1: Error de conexión con Futu

ERROR: 连接富途OpenD失败

Pasos de solución:

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

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

# 3. 重启服务
python main_enhanced.py

Problema 2: Error de caché

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

Solución:

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

Problema 3: Error al calcular indicadores técnicos

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

Solución:

# 清理缓存，重新获取数据
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: Llamada MCP cancelada

ERROR: Received request before initialization was complete

Solución:

# 使用稳定的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 verificación de salud

# 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 rendimiento esperadas

Métrica	Primera solicitud	Caché activa	Valor objetivo
Cotización de acciones	< 200ms	< 10ms	✅
Datos de velas	< 500ms	< 1ms	✅
Indicadores técnicos	< 300ms	< 50ms	✅
Verificación de salud	< 10ms	-	✅

📦 Implementación en entorno de producción

Implementación con 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

Implementación como servicio 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

🔮 Comparación y selección de versiones

Guía de selección de versión de servicio

Versión	Puerto	Características	Escenario de uso	Estabilidad
main_enhanced.py	8001	Protocolo dual MCP + HTTP	Integración con asistentes de IA	95% ⚠️
main_enhanced_simple_alternative.py	8002	API HTTP pura	Entorno de producción	100% ✅
main_simple.py	8000	Funciones básicas	Uso ligero	100% ✅

Selección recomendada:

🔥 Entorno de producción: main_enhanced_simple_alternative.py (puerto 8002)
🤖 Integración con IA: main_enhanced.py (puerto 8001) + API HTTP como alternativa
⚡ Escenario ligero: main_simple.py (puerto 8000)

🤝 Obtener soporte

Autoservicio

📖 Documentación de API: http://localhost:8001/docs
🔍 Verificación de salud: http://localhost:8001/health
📊 Estado de caché: http://localhost:8001/api/cache/status

Soporte comunitario

GitHub Issues: Reportar problema
Discusión: GitHub Discussions

Diagnóstico rápido

Cuando encuentre problemas, proporcione la siguiente información:

# 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  # 如果有日志文件

📜 Licencia

Este proyecto está bajo la licencia MIT - consulte el archivo LICENSE para más detalles

🎉 ¡Comience su viaje de trading cuantitativo profesional!

🔥 De proxy de API a plataforma de análisis cuantitativo | Mejora de rendimiento del 99%+ | Estabilidad de nivel empresarial