trader-broker

¿Qué hace trader-broker?

El Ejecutor de Órdenes es el único skill de este paquete que puede generar una orden real, por lo que es el más estricto. Una orden llega al mercado solo después de tres compuertas separadas, cada vez, para cada orden:

1. trader-risk ha aprobado esta orden exacta hoy (coincide por huella).
2. El usuario ha escrito un sí explícito para esta orden en el chat.
3. El usuario ha hecho clic en Permitir una vez en la tarjeta de permiso de Claude, que aparece porque la herramienta de órdenes está configurada como "Necesita aprobación".

Dos síes del usuario, un APTO de las reglas. Sin sí, no hay orden.

${CLAUDE_SKILL_DIR} a continuación es la carpeta de este skill (donde reside este SKILL.md).

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # cada ticket, LISTO o no
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "sí"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --status placed --broker-id ID --filled-qty 8 --filled-price 364.20
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol TSLA --side sell --qty 8 --price 370.04
python3 "${CLAUDE_SKILL_DIR}/ticket.py" flatten --symbol TSLA --qty 8
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py nunca habla con un bróker. Renderiza tickets, verifica que una respuesta sea un sí real para esa orden, construye el ticket de cierre y mantiene el registro en trader/state/broker.json. --now "2026-10-19 10:15" fija el reloj (hora de Nueva York).

Qué lee y escribe

archivo	qué
trader/orders.json	las órdenes propuestas (trader-budget lo escribe; flatten lo reemplaza)
trader/state/risk.json	los veredictos de trader-risk; solo un APTO de hoy está LISTO
trader/state/broker.json	cada sí, no, colocado, fallido y llenado, con la pérdida máxima de cada entrada
trader/portfolio.json	efectivo y acciones, actualizado por fill y por result --filled-qty
trader/plan.json	la hora de cierre para flatten

Configuración A: Alpaca (servidor MCP oficial, Claude Desktop)

El servidor propio de Alpaca está en github.com/alpacahq/alpaca-mcp-server (MIT). Se ejecuta en el ordenador del usuario dentro de Claude Desktop. No está en el directorio de conectores de Claude. Opera en una cuenta paper a menos que se indique lo contrario. Verificado contra su código fuente el 2026-10-20 (versión 2.4.0).

1. El usuario crea una cuenta de Alpaca y genera claves API de paper trading en el panel de Alpaca. Las claves de papel son diferentes de las claves reales.
2. El usuario instala uv (que proporciona uvx), desde docs.astral.sh/uv.
3. En Claude Desktop: Configuración > Desarrollador > Editar Config. Eso abre claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). El usuario añade este bloque (también en claude_desktop_config.example.json aquí) y escribe sus propias claves en el archivo:

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "pega aquí tu clave de papel, solo en este archivo",
        "ALPACA_SECRET_KEY": "pega aquí tu secreto de papel, solo en este archivo",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

El bloque env entrega las claves al servidor como variables de entorno. Las claves nunca van en el chat. Nunca las pidas, nunca leas este archivo de vuelta a la conversación, y si el usuario pega una clave de todos modos, pídele que elimine ese mensaje y genere nuevas claves en el panel de Alpaca. ALPACA_PAPER_TRADE ya es verdadero por defecto; escribirlo lo hace visible. ALPACA_TOOLSETS es opcional y oculta las herramientas que no necesita. 4. Reinicia Claude Desktop. 5. Configura los permisos de las herramientas. Personalizar > Conectores (Configuración > Conectores en versiones anteriores), abre alpaca, y para cada herramienta elige Permitir siempre, Necesita aprobación o Bloqueado:

• place_stock_order: Necesita aprobación. Nunca Permitir siempre.
• cualquier otra herramienta que coloque, cambie, cancele o cierre algo (cancel_order_by_id, replace_order_by_id, close_position, update_account_config): Necesita aprobación.
• place_option_order, place_crypto_order, close_all_positions, cancel_all_orders, exercise_options_position, do_not_exercise_options_position: Bloqueado a menos que el usuario tenga un motivo y lo diga.
• herramientas de solo lectura (get_account_info, get_all_positions, get_open_position, get_orders, get_clock, get_stock_snapshot, get_stock_latest_quote): Permitir siempre está bien.

6. Verifícalo: pídele a Claude la información de la cuenta de Alpaca (solo lectura) y confirma en el panel de Alpaca que es la cuenta de papel.

En Claude Code en lugar de Claude Desktop, mantén la herramienta de órdenes en 'ask' en .claude/settings.json: "permissions": {"ask": ["mcp__alpaca__place_stock_order"]}, y nunca pongas una herramienta de órdenes en allow.

Órdenes bracket en Alpaca. place_stock_order acepta take_profit_limit_price y stop_loss_stop_price (y un stop_loss_limit_price opcional). Cuando alguno está presente, el servidor establece order_class a "bracket" por sí mismo; trader-budget lo escribe de todos modos para que el ticket lo muestre. Un bracket es solo acciones enteras, con time_in_force day o gtc. Después de que la entrada se llena, el stop-loss y el take-profit esperan en el bróker como dos órdenes que se cancelan mutuamente. También son órdenes intradía, por lo que terminan al cierre: una razón más para estar plano para entonces.

Configuración B: Interactive Brokers (conector en el directorio de Claude)

Interactive Brokers publica un conector verificado: claude.ai/directory/interactive-brokers (URL del conector https://api.ibkr.com/v1/api/mcp). Añádelo desde Personalizar > Conectores > Examinar conectores e inicia sesión en IBKR allí, no en el chat. Su descripción dice que Claude puede redactar instrucciones de trading que se envían a la cuenta IBKR del usuario para su revisión y aprobación, y que Claude nunca envía órdenes directamente al mercado. Entonces, con IBKR el sí final ocurre en IBKR también. Establece "broker": "ibkr" en trader/config.json. Configura sus herramientas que redactan órdenes en Necesita aprobación también.

Pasos: la entrada

1. ticket.py show. Solo los tickets LISTO van al usuario. Un ticket que NO está LISTO o BLOQUEADO vuelve a /trader-risk.
2. Muestra UN ticket y pregunta: "¿Colocar esta orden? Responde sí o no." Una orden por pregunta. Nunca ofrezcas "sí a todo".
3. Ejecuta ticket.py approve --index N --reply "<la respuesta del usuario, palabra por palabra>". Si imprime "No registrado", la respuesta no fue un sí explícito para esta orden (por ejemplo, "claro", "sí a todo", o un sí que nombra una acción o cantidad diferente). Pregunta de nuevo. Nunca conviertas una respuesta en un sí tú mismo.
4. Solo después de "Tu sí ha sido registrado", llama a place_stock_order exactamente con el JSON que imprimió el ticket. Aparece la tarjeta de Claude: Permitir una vez o Denegar.
5. Registra lo que ocurrió: ticket.py result --index N --status placed --broker-id <id> --filled-qty Q --filled-price P (el fill de la respuesta o de get_open_position), o --status denied, o --status failed con --note. Una orden fallida no se reintenta sin una nueva verificación y un nuevo sí. El registro mantiene la pérdida máxima de la entrada para el límite diario de trader-risk.

Pasos: mientras está abierta, y salir al cierre

• trader-alerts vigila el stop, el target y la hora de cierre (alerts.py add --from-plan). Las órdenes propias del bracket se encargan del stopp.
• Cuando el stop-loss o el take-profit se llenan, regístralo: ticket.py fill --symbol TSLA --side sell --qty 8 --price 358.32.
• Para flat_by (15:55 Nueva York), cualquier cosa que aún esté abierta se cierra:
  1. Pregunta a Alpaca cuántas acciones se tienen: get_open_position (solo lectura).
  2. ticket.py flatten --symbol TSLA --qty 8 escribe una venta a mercado para esas acciones en trader/orders.json.
  3. /trader-risk. Una venta que solo cierra lo que el usuario posee nunca es bloqueada por los límites diarios o la ventana de entrada.
  4. ticket.py show, luego el sí del usuario para esa orden, como arriba.
  5. El stop-loss y el take-profit del bracket aún retienen esas acciones, por lo que Alpaca rechaza una nueva venta hasta que se cancelen: get_orders (estado abierto, anidado true) los muestra; cancel_order_by_id cada uno (Necesita aprobación). Luego place_stock_order con el ticket, luego result.

Ejemplo: la vista

ORDEN 1 de 1, cuenta PAPER, Alpaca
  COMPRAR 8 TSLA, mercado, válida por hoy
  stop-loss 358.32
  take-profit 370.04
  pérdida máxima aprox. $46.88 si el stop se llena a 358.32 (puede llenarse peor en un mercado rápido)
  motivo: ruptura del rango de apertura en TSLA: 8 acciones, limitado por tu pérdida máxima de $50 por operación (8 x 5.86 = $46.88 en el stop)
  LISTO: trader-risk APTO, esperando tu sí
  Claude llamará a place_stock_order exactamente con:
    {"symbol": "TSLA", "side": "buy", "qty": "8", "type": "market", "time_in_force": "day",
     "order_class": "bracket", "take_profit_limit_price": "370.04", "stop_loss_stop_price": "358.32"}

El usuario responde "sí". Claude lo registra, llama a place_stock_order, y la tarjeta muestra "Claude quiere usar Place stock order" con ese JSON y dos botones: Permitir una vez, Denegar. Permitir una vez lo envía a la cuenta de papel. El why y el plan permanecen en el archivo; nunca se envían.

Lo que nunca hace

• Nunca coloca una orden sin las tres compuertas, y nunca dos órdenes con un solo sí.
• Nunca coloca órdenes desde una tarea programada o en segundo plano: no hay nadie para decir sí.
• Nunca pide, lee, almacena ni repite claves API o contraseñas.
• Nunca cambia ALPACA_PAPER_TRADE o "paper" a real. El usuario lo hace por sí mismo.
• Nunca llama a close_all_positions, cancel_all_orders, herramientas de opciones o cripto por su cuenta.
• Nunca promete un precio de fill: una orden a mercado y un stop se llenan al precio que dé el mercado.

Seguridad

• Educación y herramientas, no asesoramiento financiero. Un APTO es una verificación de reglas, no una recomendación.
• Paper trading por defecto ("paper": true). Pasar a real es decisión del usuario, en su propia configuración.
• Nada en este paquete coloca una orden excepto trader-broker, y solo cuando se cumplen las tres condiciones: trader-risk ha aprobado esa orden exacta hoy, el usuario ha escrito un sí explícito para esa orden en el chat, y el usuario ha hecho clic en Permitir una vez en la tarjeta de Claude porque la herramienta de órdenes está configurada como "Necesita aprobación" (Personalizar > Conectores > permisos de herramientas). Nunca configures una herramienta de órdenes en "Permitir siempre".
• Sin opciones, margen, venta en corto ni apalancamiento a menos que la configuración lo permita y el usuario lo confirme.
• Las claves del bróker viven en variables de entorno o en la configuración de Claude Desktop, nunca en el chat.