Tu IA, conectadaa MarketForge.

1. Cómo funciona

MCP permite que un cliente de IA utilice herramientas de MarketForge. Tú conversas con tu IA; ella consulta datos o propone acciones mediante esas herramientas, dentro de los permisos de tu cuenta.

MarketForge MCP se ejecuta en tu ordenador. Tu cliente de IA lo inicia y se comunica con él mediante STDIO; el MCP se conecta a MarketForge por HTTPS. No debes añadir una URL de servidor MCP remoto.

El modelo y su suscripción pertenecen al cliente de IA que elijas. MarketForge no incluye un modelo ni pide una clave de un proveedor de IA. Los datos devueltos por las herramientas llegan a ese cliente: revisa sus condiciones de privacidad antes de compartir información de tu cuenta.

2. Requisitos y descarga

Necesitas Python 3.12 o posterior, un cliente de IA compatible con servidores MCP locales por STDIO, acceso a Internet y una cuenta MarketForge para autorizar las herramientas. Las acciones disponibles siguen los permisos y límites de tu plan.

El cliente admite macOS, Linux y Windows con un llavero seguro disponible. La compatibilidad del cliente de IA que elijas depende de su proveedor; esta guía no implica que todos los clientes existan en los tres sistemas.

Descarga el código fuente, descomprime el ZIP y abre una terminal dentro de la carpeta marketforge-assistant-main. Los comandos siguientes instalan ese código en un entorno virtual; no requieren activar el entorno ni descargar un paquete desde PyPI.

La guía puede consultarse sin cuenta. La descarga de código requiere acceso autorizado al repositorio de GitHub; todavía no hay un paquete de instalación público. Si GitHub muestra 404, comprueba que hayas iniciado sesión con una cuenta que tenga acceso antes de continuar.

3. Instalar en macOS

Usa Terminal y comprueba que python3 sea Python 3.12 o posterior. Los tokens se guardan en el llavero de macOS (Keychain), que debe estar disponible y desbloqueado.

Tras instalar, el comando login abre el navegador. Entra en MarketForge, revisa la cuenta y los permisos solicitados y confirma el consentimiento. Mantén la terminal abierta hasta que termine; status permite consultar el estado sin revelar tokens.

python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/marketforge-mcp login
.venv/bin/marketforge-mcp status

4. Instalar en Linux

Comprueba que python3 sea Python 3.12 o posterior y que tu distribución incluya soporte para venv y pip. Usa tu sesión de escritorio, con D-Bus y un llavero Secret Service disponible y desbloqueado, como el de GNOME. Un servidor sin sesión de llavero necesita preparar ese servicio antes del login.

Si aparece un error de llavero, comprueba la sesión y los permisos de D-Bus. El cliente rechaza guardar tokens en texto plano; no copies credenciales a archivos para evitar ese error.

python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/marketforge-mcp login
.venv/bin/marketforge-mcp status

5. Instalar en Windows

Usa PowerShell con Python 3.12 o posterior. Este ejemplo selecciona Python 3.12 mediante el lanzador py; si tienes otra versión compatible, selecciona esa versión. Los tokens se guardan en el Administrador de credenciales de Windows.

Ejecuta los comandos desde la carpeta descomprimida. No necesitas activar scripts de PowerShell ni cambiar su política de ejecución. Si usas WSL, sigue la guía de Linux y prepara un llavero en esa sesión: el llavero de Windows no se hereda automáticamente.

py -3.12 --version
py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install .
.venv\Scripts\marketforge-mcp.exe login
.venv\Scripts\marketforge-mcp.exe status

6. Conectar Codex

Después del login local, registra el ejecutable en Codex. Sustituye la ruta de ejemplo por la ruta absoluta de tu carpeta; las comillas permiten utilizar rutas con espacios. Reinicia o reconecta el cliente para que cargue el servidor.

En un cliente con formulario de configuración, añade un servidor STDIO con el ejecutable como comando y serve como argumento. Usa el mismo perfil y usuario del sistema con el que autorizaste MarketForge.

En la sección existente [mcp_servers.marketforge] de la configuración de Codex, establece default_tools_approval_mode = "writes" para pedir aprobación de las herramientas de escritura. Conserva esa confirmación al gestionar bots o estrategias.

codex mcp add marketforge -- "/ruta/absoluta/marketforge-assistant-main/.venv/bin/marketforge-mcp" serve
codex mcp list

codex mcp add marketforge -- "C:\ruta\marketforge-assistant-main\.venv\Scripts\marketforge-mcp.exe" serve
codex mcp list

7. Conectar Claude Code u otro cliente

Claude Code también puede iniciar el servidor local. Después del login de MarketForge, registra el comando de tu sistema y consulta /mcp dentro de Claude Code para revisar la conexión y sus herramientas.

Para otro cliente, busca su configuración de servidores MCP locales: transporte STDIO, ruta absoluta al ejecutable y argumento serve. Si solo admite servidores remotos por HTTP, no puede conectar directamente este cliente local. Mantén sus aprobaciones de escritura activadas.

claude mcp add --transport stdio marketforge -- "/ruta/absoluta/marketforge-assistant-main/.venv/bin/marketforge-mcp" serve

claude mcp add --transport stdio marketforge -- "C:\ruta\marketforge-assistant-main\.venv\Scripts\marketforge-mcp.exe" serve

8. Qué puedes hacer

Pide primero una consulta o propuesta y revisa los datos antes de aprobar cambios. El catálogo disponible incluye:

• Mercados: consultar instrumentos, cotizaciones, velas cerradas y análisis técnico determinista.
• Estrategias: consultar el esquema de Strategy Studio, validar contenido y crear, guardar o eliminar borradores.
• Backtesting: consultar capacidades y compatibilidad, obtener reglas y datos de Binance, crear estudios, abrir la simulación en tu navegador y consultar o guardar resultados con Monte Carlo por bloques. El servidor no calcula simulaciones.
• Conexiones: consultar identificadores, proveedor, entorno, estado, capacidades y comisiones, sin acceder a sus credenciales.
• Bots: revisar compatibilidad, configuración, ejecuciones y eventos; crear, editar, iniciar, pausar, restablecer o archivar bots con aprobación.
• Historial de bots: descargar todos los logs, ejecuciones y órdenes de un bot en un único CSV, incluidas las páginas anteriores. El cliente de IA debe admitir archivos o recursos MCP adjuntos.
• Cuenta: consultar cartera, posiciones, historial de órdenes, perfil, preferencias, límites y autorizaciones MCP; revocar una autorización de tu cuenta.

9. Ejemplos para tu IA

Con el MCP conectado, puedes comenzar con estas peticiones. Son ejemplos de conversación; los resultados dependen de los datos disponibles en tu cuenta.

• «Resume mis bots activos, sus últimas ejecuciones y los errores que requieren revisión.»
• «Descarga los logs y todo el historial de este bot en un único CSV.»
• «Consulta las velas cerradas de este par y explica su RSI, EMA y ATR, indicando el periodo analizado.»
• «Compara las comisiones Spot de mis conexiones disponibles.»
• «Consulta el catálogo de backtesting, comprueba mi estrategia y prepara un estudio con fechas y costes explícitos. Ejecútalo en mi navegador y resume el resultado guardado.»
• «Prepara un borrador de estrategia, valida sus nodos y muéstrame los cambios antes de guardarlo.»
• «Comprueba si esta estrategia es compatible con mi conexión Testnet y propón un bot; espera mi aprobación antes de crearlo.»

10. Permisos, límites y fondos reales

El login usa OAuth con PKCE y un retorno temporal al propio ordenador. MarketForge vincula los permisos a la cuenta autorizada. Los tokens permanecen en el llavero del sistema y no se entregan al modelo; la sesión del navegador no sustituye este login local.

Las lecturas consultan datos. Las escrituras modifican estrategias, estudios de backtesting, resultados, bots o autorizaciones y requieren tu intención explícita y aprobación en el cliente de IA. Los límites y la propiedad de los datos se comprueban también en MarketForge.

Backtesting requiere los permisos backtests:read y backtests:write. Tras actualizar el cliente, vuelve a iniciar sesión para consentirlos y reconecta el MCP. Mantén abierta la pestaña autenticada mientras calcula; puedes cancelar allí. Abrirla no confirma que haya terminado: la IA debe consultar el resultado guardado. La simulación por velas no reconstruye el libro y los resultados no están verificados por el servidor. El catálogo indica las limitaciones de estrategias duales y otras operaciones.

La descarga completa de un bot utiliza los permisos existentes de lectura de bots y órdenes. Tras actualizar el MCP, reconéctalo en tu cliente de IA para descubrir la herramienta download_bot_history y guardar su CSV adjunto.

Las acciones Mainnet que pueden afectar fondos exigen además confirmar explícitamente el entorno y los fondos reales. Pausar, restablecer o archivar un bot no liquida por sí solo su posición. Según la configuración, sus órdenes pendientes pueden conservarse y ejecutarse después.

El MCP no permite cambiar llaves de paso, recuperar cuentas, leer o guardar secretos de exchanges, crear conexiones, publicar estrategias, enviar o cancelar órdenes manuales directas ni dibujar en gráficos. No proporciona al modelo acceso al sistema de archivos, shell o código de MarketForge.

11. Perfiles y revocación

El perfil predeterminado se llama default. Para separar cuentas, añade --profile nombre tanto a login como a serve; registra ese mismo argumento en el cliente de IA. Los clientes del mismo ordenador pueden compartir un perfil, pero cada equipo debe tener su propio login y autorización.

La autorización permanece activa hasta revocarla; los tokens de acceso duran 15 minutos y se renuevan automáticamente. Usa logout para revocar la autorización y retirar la credencial local. Revocar todas las sesiones desde Seguridad en la web también invalida todos los grants MCP activos.

Quitar el servidor de la configuración del cliente de IA no revoca por sí solo el acceso a MarketForge. No compartas ni copies el llavero entre equipos.

.venv/bin/marketforge-mcp logout

.venv\Scripts\marketforge-mcp.exe logout

12. Solución de problemas

Si el cliente no encuentra el servidor, comprueba la ruta absoluta, el entorno virtual y status desde la terminal. Ejecuta login y el cliente de IA con el mismo usuario del sistema. Tras actualizar el paquete, reconecta el servidor para cargar el catálogo actual.

Si login no abre el navegador, abre manualmente la URL que muestra la terminal en ese mismo ordenador y conserva la terminal abierta. Si falta el llavero, desbloquéalo y revisa su sesión; no introduzcas tokens ni credenciales en la conversación.

Si la autorización fue revocada, vuelve a hacer login. Si todavía queda un perfil anterior, ejecuta primero logout. Un fallo temporal de red conserva el perfil y permite reintentar una lectura cuando el servicio vuelva a estar disponible.

Si una escritura pierde la respuesta, consulta el estado antes de repetirla. Conserva el identificador de la petición y la revisión originales cuando existan; no crees otra operación ni apruebes automáticamente una revisión nueva para eludir un conflicto.

Si el cliente indica un guardado incierto de credenciales, recupera el perfil con logout. Usa logout --remote-revoked únicamente después de confirmar que has revocado ese grant en MarketForge. No borres manualmente las marcas de seguridad del perfil.