trading-mcp

Servicio MCP para datos de trading e indicadores técnicos, construido sobre uv + pydantic + akshare + TA-Lib.

Contenido del proyecto

• Proporciona consultas de datos de mercado bursátil y cálculo de indicadores técnicos básicos (velas, RSI, MA, MACD).

• Proporciona consultas de datos fundamentales a medio y largo plazo (indicadores principales de acciones A, tres estados financieros principales de acciones de EE. UU., indicadores principales de acciones de EE. UU.).

• Capa de acceso a datos de mercado unificada, compatible con acciones A y acciones de EE. UU. (por ejemplo, AAPL.US).

• Interfaz de herramientas MCP, compatible con salida en formato Markdown o JSON.

Arquitectura del proyecto

• data/: Capa de acceso a datos de mercado. Interfaz MarketDataClient + implementación AkshareMarketDataClient.

• services/: Capa de servicios de negocio. Convierte las cotizaciones originales en estructuras estándar y dirige el cálculo de indicadores.

• indicators/: Encapsulación del motor de indicadores. Llamadas unificadas basadas en TA-Lib.

• models/: Modelos de solicitud y respuesta de herramientas (Pydantic).

• utils/: Formateo de salida MCP (tablas Markdown, etc.).

• mcp_app.py / main.py: Punto de entrada del servicio MCP y registro de herramientas.

Estructura de directorios

• config/: Definición de configuración (Pydantic Settings).

• data/: Implementación del cliente de datos de mercado.

• indicators/: Motor de cálculo de indicadores.

• models/: Modelos de solicitud/respuesta.

• services/: Capa de servicios de negocio.

• tests/: Pruebas unitarias.

• utils/: Formateo de salida y herramientas auxiliares.

• mcp_app.py: Registro de herramientas MCP.

• main.py: Punto de entrada para iniciar el servicio.

Instalación y dependencias

1. Instalar dependencias:

uv sync --extra dev

2. Instalar librerías del sistema TA-Lib:

• macOS: brew install ta-lib

• Debian/Ubuntu: sudo apt-get install libta-lib0 libta-lib0-dev

• Windows: Usar el wheel precompilado correspondiente a la versión de Python

Instrucciones de configuración La configuración se sobrescribe mediante el prefijo de variables de entorno TRADING_MCP_:

export TRADING_MCP_ENVIRONMENT=dev
export TRADING_MCP_DATA_DIR=./data
export TRADING_MCP_DEFAULT_SYMBOL=000001
export TRADING_MCP_HOST=0.0.0.0
export TRADING_MCP_PORT=8000
export TRADING_MCP_AKSHARE_PROXY_ENABLED=true
export TRADING_MCP_AKSHARE_PROXY_AUTH_IP=***
export TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN=*** TRADING_MCP_AKSHARE_PROXY_RETRY=30

Significado de los campos:

• TRADING_MCP_ENVIRONMENT: Identificador del entorno de ejecución (ej. dev / test / prod).

• TRADING_MCP_DATA_DIR: Directorio de datos local.

• TRADING_MCP_DEFAULT_SYMBOL: Activo de cotización predeterminado.

• TRADING_MCP_HOST: Dirección de escucha del servicio MCP.

• TRADING_MCP_PORT: Puerto del servicio MCP.

• TRADING_MCP_AKSHARE_PROXY_ENABLED: Si se habilita akshare-proxy-patch.

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP: IP de la pasarela de autorización de akshare-proxy-patch; si no se configura, no se instalará el parche.

• TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN: Token de autorización opcional.

• TRADING_MCP_AKSHARE_PROXY_RETRY: Número de reintentos internos del parche.

Notas sobre el proxy anti-scraping de East Money:

• El proyecto incluye akshare-proxy-patch, que intentará instalarse automáticamente al importar data/akshare_client.py.

• Solo se habilitará si se configura TRADING_MCP_AKSHARE_PROXY_AUTH_IP y TRADING_MCP_AKSHARE_PROXY_ENABLED=true.

• El parche solo interceptará solicitudes a dominios relacionados con East Money y no afectará a otros sitios no objetivo.

Uso en Python

from trading_mcp.config import Settings
from trading_mcp.data import AkshareMarketDataClient
from trading_mcp.indicators import IndicatorEngine

settings = Settings(environment="dev", data_dir="./data", default_symbol="000001")
client = AkshareMarketDataClient()
frame = client.fetch(settings.default_symbol, "2024-01-01", "2024-02-01")

engine = IndicatorEngine()
close_series = frame["close"] if "close" in frame.columns else frame.iloc[:, 0]
result = engine.compute("sma", close_series, timeperiod=5)
print(result.tail())

Servicio MCP Iniciar el servicio MCP (HTTP transmitible):

python main.py

Iniciar el Inspector MCP (adaptado para WSL, accesible desde el host):

./dev.sh

Por defecto se utilizará la siguiente configuración del Inspector:

• MCP_INSPECTOR_HOST=0.0.0.0

• MCP_INSPECTOR_CLIENT_PORT=6274

• MCP_INSPECTOR_SERVER_PORT=6277

• MCP_INSPECTOR_AUTO_OPEN=false

Acceder preferiblemente desde el navegador del host Windows:

http://localhost:6274

Si el reenvío de localhost de WSL no está habilitado en la máquina local, también puede ejecutar hostname -I dentro de WSL para ver la IP y luego acceder desde el host a http://<wsl-ip>:6274.

Si solo desea acceder desde el entorno Linux local, puede sobrescribirlo con:

MCP_INSPECTOR_HOST=127.0.0.1 ./dev.sh

Nota: El proxy del Inspector tiene la capacidad de iniciar procesos locales. 0.0.0.0 solo debe usarse en entornos de red de confianza.

Herramientas disponibles:

• trading_kline(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_macd(symbol, limit=30, fast_period=12, slow_period=26, signal_period=9, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_rsi(symbol, limit=30, period=14, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_ma(symbol, limit=30, period=20, ma_type="sma", offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_volume(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_em(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_rank_em(indicator="5日", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_rank_em(indicator="今日", sector_type="行业资金流", sort_by="主力净流入", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_summary_em(symbol, indicator="今日", limit=30, offset=0, response_format="markdown")

• trading_fundamental_cn_indicators(symbol, indicator="按报告期", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_report(stock, symbol="资产负债表", indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_indicators(symbol, indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_summary_ths(limit=30, offset=0, response_format="markdown")

• trading_industry_index_ths(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_name_em(limit=30, offset=0, response_format="markdown")

• trading_board_change_em(limit=30, offset=0, response_format="markdown")

• trading_industry_spot_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_cons_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_hist_em(symbol, period="日k", adjust="none", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_hist_min_em(symbol, period="5", limit=30, offset=0, response_format="markdown")

• trading_info_global_em(limit=30, offset=0, response_format="markdown")

Notas sobre los parámetros de trading_fundamental_cn_indicators:

• Enum indicator: 按报告期 (por periodo de informe), 按单季度 (por trimestre individual)

• Entrada compatible para symbol: 000001, 000001.SZ, 600519.SH (autocompletado o normalización de sufijos)

• Los resultados fundamentales se devuelven en formato de fila original: columns + items

Notas sobre los parámetros de trading_fundamental_us_report:

• Enum symbol (tipo de informe): 资产负债表 (Balance general), 综合损益表 (Estado de resultados), 现金流量表 (Estado de flujo de efectivo)

• Enum indicator (periodo del informe): 年报 (Informe anual), 单季报 (Informe trimestral), 累计季报 (Informe trimestral acumulado)

• Entrada compatible para stock: TSLA, AAPL.US, 105.AAPL, BRK.B (normalizado internamente al ticker reconocible por AkShare)

Notas sobre los parámetros de trading_fundamental_us_indicators:

• Enum indicator: 年报, 单季报, 累计季报

• Entrada compatible para symbol: TSLA, AAPL.US, 105.AAPL, BRK.B

• Los resultados fundamentales se devuelven en formato de fila original: columns + items

Notas sobre los campos de trading_volume:

• Campos devueltos: timestamp, volume, amount, turnover_rate

• Estrategia de unidades: Se conservan las unidades originales de la fuente de datos y se devuelven a través de los campos de respuesta

  • Acciones A: volume_unit=lot, amount_unit=CNY

  • Acciones de EE. UU.: volume_unit=share, amount_unit=USD

  • turnover_rate_unit=percent

• Cuando los datos semanales/mensuales se agregan a partir de líneas diarias, turnover_rate puede ser null

Notas sobre las herramientas de flujo de capital:

• trading_fund_flow_individual_em: Flujo de capital de acciones individuales de East Money, symbol admite 000001, 600519.SH, 830799.BJ

• trading_fund_flow_individual_rank_em: Ranking de flujo de capital de acciones individuales de East Money

  • Enum indicator: 今日 (Hoy), 3日, 5日, 10日

• trading_fund_flow_sector_rank_em: Ranking de flujo de capital de sectores de East Money

  • Enum indicator: 今日, 5日, 10日

  • Enum sector_type: 行业资金流 (Flujo de capital industrial), 概念资金流 (Flujo de capital conceptual), 地域资金流 (Flujo de capital regional)

  • Enum sort_by: 涨跌幅 (Variación de precio), 主力净流入 (Entrada neta principal); por defecto ordenado descendentemente por 主力净流入

• Cuando la interfaz de ranking de East Money no está disponible:

  • El ranking de acciones individuales volverá al ranking de flujo de capital de acciones de Tonghuashun

  • El ranking de sectores industriales/conceptuales volverá al ranking correspondiente de Tonghuashun

  • Después del retroceso, las columnas devueltas pueden diferir de las columnas originales de East Money; el 地域资金流 no tiene retroceso

• trading_fund_flow_sector_summary_em: Flujo de capital de las acciones constituyentes de un sector específico

  • Por defecto usa East Money, en caso de fallo vuelve a Tonghuashun

  • symbol es el nombre del sector, ej. 电源设备 (Equipos de energía), 风电设备 (Equipos de energía eólica)

  • Enum indicator: 今日, 5日, 10日

  • Después del retroceso, las columnas devueltas pueden diferir de las columnas originales de East Money

• Los resultados del flujo de capital se devuelven unificadamente como tablas originales: columns + items

Notas sobre los símbolos:

• Ejemplo de acciones A: 000001, 300308.SZ

• Ejemplo de acciones de EE. UU.: AAPL.US, AAPL, 105.AAPL, BRK.B

Notas sobre las herramientas de sectores industriales:

• trading_industry_summary_ths: Tabla resumen de sectores de Tonghuashun, devuelve los campos de resumen de sector originales

• trading_industry_index_ths: Índice sectorial de Tonghuashun, symbol es el nombre del sector, admite start_date / end_date

• trading_industry_name_em: Lista de nombres de sectores industriales de East Money

• trading_board_change_em: Detalles de cambios inusuales en sectores de East Money durante el día

• trading_industry_spot_em: Cotizaciones en tiempo real de sectores industriales de East Money, symbol es el nombre del sector

• trading_industry_cons_em: Acciones constituyentes de sectores industriales de East Money, symbol es el nombre del sector

• trading_industry_hist_em: Cotizaciones históricas de sectores industriales de East Money

  • Enum period: 日k (Diario), 周k (Semanal), 月k (Mensual)

  • Enum adjust: none, qfq (ajuste hacia adelante), hfq (ajuste hacia atrás); donde none significa sin ajuste

• trading_industry_hist_min_em: Cotizaciones históricas intradiarias de sectores industriales de East Money

  • Enum period: 1, 5, 15, 30, 60

• Los resultados de sectores industriales se devuelven unificadamente como tablas originales: columns + items

Notas sobre las herramientas de información:

• trading_info_global_em: Noticias financieras globales de East Money

• Los resultados de información se devuelven unificadamente como tablas originales: columns + items

Estructura de respuesta (structuredContent)

{
  "stock": "TSLA",
  "symbol": "资产负债表",
  "indicator": "年报",
  "columns": ["REPORT_DATE", "ITEM_NAME", "AMOUNT"],
  "items": [],
  "count": 0,
  "total": 0,
  "limit": 30,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "start_date": null,
  "end_date": null
}

Flujo de interacción de datos MCP (Arquitectura y diagrama de secuencia)

A continuación, se utiliza Mermaid para dibujar la arquitectura principal de interacción de datos y el diagrama de secuencia del MCP actual, para ayudar a comprender la ruta de flujo de las solicitudes dentro del sistema.

Esquema de arquitectura (Flowchart)

flowchart LR
  Client[Client / User] -->|HTTP/Stream 请求| MCP[MCP Server]
  MCP -->|调用工具接口| API[Tool Dispatcher / Handlers]
  API --> Market[MarketDataClient (Akshare / Providers)]
  Market -->|行情数据| Storage[Local Cache / Data Dir]
  API --> Indicator[IndicatorEngine (TA-Lib)]
  Indicator -->|指标结果| Formatter[Response Formatter (Markdown / JSON)]
  Formatter -->|返回| Client
  Market -.->|必要时| Proxy[akshare-proxy-patch]
  MCP -->|注册 & 管理| Inspector[MCP Inspector]

Explicación:

• MCP Server: Recibe solicitudes externas (HTTP/stream), responsable de analizar la solicitud y llamar a las herramientas internas.

• Tool Dispatcher: Enruta la solicitud a la herramienta específica (ej. trading_kline, trading_macd).

• MarketDataClient: Capa de acceso a datos de mercado unificada, actualmente implementada principalmente con Akshare, admite parches de proxy.

• IndicatorEngine: Llama a TA-Lib o algoritmos integrados para calcular indicadores técnicos.

• Response Formatter: Convierte datos estructurados en formato de respuesta MCP Markdown o JSON.

• Local Cache/Storage: Utilizado para almacenamiento en caché a corto plazo y datos históricos para reducir las llamadas a la API.

Diagrama de secuencia (Sequence Diagram)

sequenceDiagram
  participant U as Client/User
  participant M as MCP Server
  participant D as Tool Dispatcher
  participant MD as MarketDataClient
  participant I as IndicatorEngine
  participant F as Formatter

  U->>M: 发起 trading_macd 请求 (symbol, start, end, params)
  M->>D: 解析并转发请求
  D->>MD: 请求历史 K 线 (symbol, start, end)
  MD-->>D: 返回原始行情数据 (OHLCV)
  D->>I: 传入行情数据与参数, 调用指标计算
  I-->>D: 返回指标结果 (MACD lines, histogram)
  D->>F: 格式化为 Markdown / JSON 的 MCP 响应
  F-->>M: 返回格式化结果
  M-->>U: 通过 HTTP Stream 返回响应 (chunked / 完整)

  alt 缓存命中
    D->>Storage: 读取缓存
    Storage-->>D: 返回缓存数据
  end

  alt 第三方被阻断/需要代理
    MD->>Proxy: 走 akshare-proxy-patch
    Proxy-->>MD: 返回代理后的数据
  end

Los dos diagramas anteriores son vistas abstractas del sistema actual; si desea detallar los diagramas con más componentes (por ejemplo: autenticación, limitación de tasa, colas, tareas asíncronas, métricas de monitoreo), dígame qué partes necesita agregar y puedo expandir y actualizar los diagramas Mermaid en el README.

Si confirma que esta actualización es correcta, enviaré los cambios a una nueva rama y los subiré, luego crearé una Pull Request para su revisión.