tossinvest-mcp

MCP servidor

Documentación

tossinvest-mcp

Resumen del programa

tossinvest-mcp es un servidor MCP local que permite usar la Open API de Toss Securities (consulta de precios actuales, órdenes, consulta de saldo, etc.) en aplicaciones compatibles con MCP como OpenAI Service, Claude Desktop o Cursor.

En pocas palabras, si registras este programa en un cliente MCP, puedes hacer solicitudes como las siguientes a la IA:

삼성전자 현재가를 조회해줘.

내 토스증권 보유 주식을 보여줘.

대기 중인 주문 목록을 보여줘.

Este programa se ejecuta únicamente en la computadora del usuario.

Advertencia más importante

La Open API de Toss Securities no cuenta con un entorno de sandbox ni de trading simulado.

Si activas las funciones de trading, se pueden crear, modificar y cancelar órdenes reales en una cuenta real. Al usarlo por primera vez, asegúrate de no activar las funciones de trading y verifica primero las funciones de consulta.

En la configuración predeterminada, las herramientas de creación, modificación y cancelación de órdenes no están registradas.

Funciones y características disponibles con el programa

Sin activar las funciones de trading, puedes usar las siguientes funciones:

Consulta de precios actuales de acciones nacionales/estadounidenses
Consulta de cotizaciones (order book)
Consulta de historial de ejecuciones recientes
Consulta de gráficos de velas (candlestick)
Consulta de límite superior/inferior (상한가/하한가)
Consulta de información básica de instrumentos
Consulta de advertencias de compra
Consulta de tipo de cambio
Consulta de horarios de mercado nacional/estadounidense
Consulta de lista de cuentas
Consulta de acciones en cartera
Consulta de monto disponible para compra
Consulta de cantidad disponible para venta
Consulta de comisiones de trading
Consulta de lista de órdenes
Consulta de detalle de órdenes

Herramientas disponibles si se activan las funciones de trading:

toss_create_order: Creación de órdenes
toss_modify_order: Modificación de órdenes
toss_cancel_order: Cancelación de órdenes

Características:

Se ejecuta con npx tossinvest-mcp, por lo que el proceso de instalación del programa es breve.
La API Key y la Secret Key se pasan mediante variables de entorno.
El token OAuth se emite automáticamente internamente y se renueva automáticamente 60 segundos antes de su expiración.
Las funciones que requieren cuenta usan por defecto la cuenta número 1 de accountSeq.
Si tienes varias cuentas o quieres usar otra cuenta, puedes cambiarlo con el valor de TOSSINVEST_ACCOUNT.
Las funciones de creación, modificación y cancelación de órdenes están desactivadas por defecto.
Incluso si activas las funciones de orden, en la configuración predeterminada no se llama a la API de órdenes si no hay un valor de confirmación confirmOrderAction: true.
Se pueden activar mediante variables de entorno protecciones como límites de orden, bloqueo de venta/orden de mercado, lista de permitidos de instrumentos y límites diarios. Todas las verificaciones se aplican forzosamente en el servidor antes de llamar a la API de órdenes de Toss Securities. (Ver 거래 가드레일 a continuación)

Importante: toss_modify_order no es un simple PATCH que modifica una orden existente en su lugar. La API de Toss Securities procesa la modificación reemplazando la orden original y devuelve un nuevo orderId después de la modificación. Para consultas de detalle de orden, re-modificaciones o cancelaciones posteriores, usa el nuevo orderId.

Método de instalación

Sigue los pasos en orden.

1. Verificar la instalación de Node.js

Abre la terminal o PowerShell e ingresa el siguiente comando.

node -v

Si aparece v20 o superior, puedes continuar al siguiente paso.

Si no tienes Node.js o la versión es baja, instala la versión LTS desde https://nodejs.org y luego abre una nueva terminal para verificar nuevamente.

2. Preparar la API Key de la Open API de Toss Securities

Inicia sesión en Toss Securities WTS y ve a la pantalla de configuración de Open API.

En esa pantalla, obtén los siguientes valores:

API Key
Secret Key

Estos dos valores deben colocarse en la configuración de MCP. No los compartas con otras personas.

3. Registrar la IP permitida

La Open API de Toss Securities solo se puede invocar desde IPs permitidas. Si falta esta configuración, se producirá un error como 허용되지 않은 IP 주소입니다..

Primero verifica la IP pública actual de tu computadora. Usa el siguiente comando.

PowerShell (Windows):

(Invoke-WebRequest -UseBasicParsing https://api.ipify.org).Content

Terminal de macOS o Linux:

curl https://api.ipify.org

Agrega la dirección IP obtenida a la lista de IPs permitidas en la pantalla de configuración de Open API de Toss Securities WTS.

Flujo aproximado:

Inicia sesión en Toss Securities WTS.
Ve al menú Configuración - Open API.
Busca el área de gestión de IPs permitidas.
Agrega la IP pública que verificaste arriba.

4. Registro en el cliente MCP

Agrega el siguiente contenido al archivo de configuración del cliente MCP o a la pantalla de configuración de Servidores MCP.

{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["tossinvest-mcp"],
      "env": {
        "TOSSINVEST_API_KEY": "발급받은-API-Key",
        "TOSSINVEST_SECRET_KEY": "발급받은-Secret-Key"
      }
    }
  }
}

Después de la configuración, cierra completamente el cliente MCP y vuelve a ejecutarlo.

En la primera ejecución, npm descargará automáticamente el paquete tossinvest-mcp.

5. Verificación del número de cuenta

Al principio no es necesario ingresar TOSSINVEST_ACCOUNT. Este programa usa por defecto la cuenta número 1 de accountSeq.

Sin embargo, si tienes varias cuentas o quieres verificar que la cuenta número 1 sea la correcta, consulta la lista de cuentas.

En el cliente MCP, haz una solicitud como la siguiente.

토스증권 계좌 목록을 조회해줘.

Busca el valor de accountSeq en la respuesta. Si quieres usar otra cuenta como cuenta predeterminada, agrega o cambia el siguiente valor en la configuración.

"TOSSINVEST_ACCOUNT": "1"

Por ejemplo, si quieres usar una cuenta cuyo accountSeq sea 2, configura de esta manera.

"TOSSINVEST_ACCOUNT": "2"

Un ejemplo completo con número de cuenta explícito es el siguiente.

{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["tossinvest-mcp"],
      "env": {
        "TOSSINVEST_API_KEY": "발급받은-API-Key",
        "TOSSINVEST_SECRET_KEY": "발급받은-Secret-Key",
        "TOSSINVEST_ACCOUNT": "1"
      }
    }
  }
}

Si no configuras TOSSINVEST_ACCOUNT, se usará el valor predeterminado 1. Si lo configuras, las funciones que requieren cuenta (como acciones en cartera, lista de órdenes, monto disponible para compra) usarán esa cuenta por defecto.

6. Prueba de las funciones de consulta

Prueba haciendo solicitudes como las siguientes en el cliente MCP.

삼성전자 현재가를 조회해줘.

내 토스증권 보유 주식을 보여줘.

AAPL 최근 체결 내역 10개를 조회해줘.

대기 중인 주문 목록을 보여줘.

Activar las funciones de trading

Verifica una vez más. La Open API de Toss Securities no tiene sandbox. Si activas las funciones de trading, se pueden enviar órdenes reales.

Para usar las funciones de trading, agrega el siguiente valor a env en la configuración de MCP.

"TOSSINVEST_ENABLE_TRADING": "true"

Ejemplo completo:

{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["tossinvest-mcp"],
      "env": {
        "TOSSINVEST_API_KEY": "발급받은-API-Key",
        "TOSSINVEST_SECRET_KEY": "발급받은-Secret-Key",
        "TOSSINVEST_ACCOUNT": "1",
        "TOSSINVEST_ENABLE_TRADING": "true"
      }
    }
  }
}

Incluso si activas las funciones de trading, las herramientas de orden no se ejecutan sin un valor de confirmación adicional. Las herramientas de creación, modificación y cancelación de órdenes solo llaman a la API de Toss Securities si la solicitud incluye confirmOrderAction: true.

Cómo ingresar `confirmOrderAction` como true

confirmOrderAction no es una variable de entorno que se coloca en la configuración de MCP. Es un valor de entrada de la solicitud de orden que se incluye cada vez que se invocan las herramientas de creación, modificación y cancelación de órdenes.

Por ejemplo, la entrada real de la herramienta de creación de órdenes tiene esta forma.

{
  "confirmOrderAction": true,
  "symbol": "005930",
  "side": "BUY",
  "orderType": "LIMIT",
  "quantity": "1",
  "price": "70000"
}

Al hacer solicitudes en lenguaje natural desde el cliente MCP, es recomendable decirlo claramente como se muestra a continuación.

토스증권에서 삼성전자 1주를 70000원 지정가로 매수 주문해줘.
실제 주문 실행을 확인하며 confirmOrderAction 값을 true로 넣어줘.

Lo mismo aplica para modificación o cancelación.

이 주문을 71000원으로 정정해줘.
실제 주문 정정을 확인하며 confirmOrderAction 값을 true로 넣어줘.

이 주문을 취소해줘.
실제 주문 취소를 확인하며 confirmOrderAction 값을 true로 넣어줘.

Según el cliente, puede mostrarse un botón de aprobación o una ventana de confirmación antes de ejecutar la herramienta de orden. En ese caso también, confirmOrderAction: true debe incluirse en la entrada de la herramienta de orden.

Ejecutar órdenes sin valor de confirmación (automatización)

Nota: La opción TOSSINVEST_YOLO_TRADING de versiones anteriores fue eliminada. Incluso si desactivas el valor de confirmación, el resto de las protecciones siguen aplicándose.

Si en un entorno de automatización es difícil ingresar confirmOrderAction: true cada vez, puedes desactivar solo el requisito de confirmación.

"TOSSINVEST_REQUIRE_ORDER_CONFIRMATION": "false"

Si desactivas este valor, se pueden enviar órdenes sin confirmOrderAction, pero las demás protecciones activadas (límites de orden, bloqueo de venta/orden de mercado, lista de permitidos de instrumentos, límites diarios, etc.) siguen aplicándose. Se recomienda encarecidamente configurar límites de monto/límite diario antes de desactivar el valor de confirmación.

Protecciones de trading (guardrails)

Las protecciones son mecanismos de seguridad que evitan que la IA "coloque órdenes por error, o demasiado grandes/con demasiada frecuencia". Todas las verificaciones se realizan dentro de este programa antes de que la orden llegue al servidor de Toss, por lo que las órdenes que exceden los límites no se envían a Toss en primer lugar.

Todas las opciones se activan agregando una línea a env en la configuración de MCP. Las opciones no activadas no se aplican (el valor predeterminado es conservador). Todos los valores se escriben como cadenas de texto. Ejemplo: "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "500000".

Resumen rápido (tabla)

Nombre	Valor predeterminado	Descripción breve
`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION`	`true`	Exige valor de confirmación `confirmOrderAction: true` por cada orden
`TOSSINVEST_MAX_ORDER_AMOUNT_KRW`	Ninguno	Límite de monto por orden (KRW)
`TOSSINVEST_MAX_ORDER_AMOUNT_USD`	Ninguno	Límite de monto por orden (USD)
`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW`	Ninguno	Límite de monto acumulado diario (KRW)
`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD`	Ninguno	Límite de monto acumulado diario (USD)
`TOSSINVEST_DAILY_MAX_ORDER_COUNT`	Ninguno	Límite de número de órdenes por día
`TOSSINVEST_ALLOWED_SYMBOLS`	Ninguno	Solo instrumentos permitidos (lista blanca)
`TOSSINVEST_ALLOW_SELL_ORDERS`	`false`	Permitir órdenes de venta
`TOSSINVEST_ALLOW_MARKET_ORDERS`	`false`	Permitir órdenes de mercado
`TOSSINVEST_MARKET_ORDER_BUFFER_PCT`	`5`	Buffer de margen (%) para cálculo de límite de mercado
`TOSSINVEST_LOCK_ACCOUNT`	`true`	Bloquear órdenes solo a la cuenta predeterminada configurada
`TOSSINVEST_GUARD_STATE_PATH`	Carpeta de datos del SO	Ruta del archivo donde se guarda el acumulado del límite diario

Descripción detallada por opción

`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION` (predeterminado: `true`)

Para crear, modificar o cancelar órdenes, la solicitud debe incluir confirmOrderAction: true para que realmente se envíe a Toss. Es el mecanismo de seguridad más básico para evitar que la IA coloque órdenes por error durante una conversación. Si es difícil ingresar el valor de confirmación cada vez (como en automatización), se puede desactivar con "false", pero incluso desactivado, los límites de monto, número, instrumentos y venta/mercado siguen aplicándose. Se recomienda encarecidamente configurar límites de monto y diarios antes de desactivarlo.

`TOSSINVEST_MAX_ORDER_AMOUNT_KRW` (predeterminado: ninguno)

Límite de monto para una sola orden en KRW. Si el monto estimado de la orden (para órdenes limitadas: cantidad × precio; para órdenes de mercado: cotización + buffer) supera este valor, se bloquea. Ejemplo: "500000" → bloquea órdenes en KRW que superen 500,000 KRW a la vez. Si no se configura, no hay límite de monto por orden.

`TOSSINVEST_MAX_ORDER_AMOUNT_USD` (predeterminado: ninguno)

Límite de monto (en USD) para una sola orden de acciones estadounidenses. Ejemplo: "1000" → bloquea órdenes que superen 1,000 USD por vez. No se realiza conversión KRW↔USD. El límite en KRW aplica solo a órdenes en KRW y el límite en USD solo a órdenes en USD, por lo que si operas en ambos mercados, configura ambos límites.

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` (predeterminado: ninguno)

Límite acumulado del monto de órdenes en KRW colocadas con este programa durante un día (hora de Corea, se reinicia a medianoche). Ejemplo: "2000000" → solo se permiten hasta 2,000,000 KRW acumulados por día. Las órdenes modificadas también se reflejan en el acumulado; las cancelaciones no se reflejan (ver "Método de cálculo del límite diario" a continuación).

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` (predeterminado: ninguno)

Versión en USD del elemento anterior. Límite de monto acumulado diario de órdenes en USD.

`TOSSINVEST_DAILY_MAX_ORDER_COUNT` (predeterminado: ninguno)

Límite de número de órdenes por día. Ejemplo: "10" → solo hasta 10 por día. Una modificación cuenta como 1 orden nueva. Las cancelaciones no se incluyen en el conteo. Útil para evitar operaciones excesivamente frecuentes.

`TOSSINVEST_ALLOWED_SYMBOLS` (predeterminado: ninguno)

Enumera separados por comas solo los instrumentos permitidos para operar. Las órdenes de instrumentos que no estén en la lista se bloquean (tanto creación como modificación). Ejemplo: "005930,AAPL,VOO" (Samsung Electronics, Apple, VOO). Para el mercado nacional se usan códigos numéricos de 6 dígitos; para EE. UU., el ticker. Si no se configura, se permiten todos los instrumentos. Úsalo si quieres "operar solo instrumentos predefinidos".

`TOSSINVEST_ALLOW_SELL_ORDERS` (predeterminado: `false`)

Indica si se permiten órdenes de venta. El valor predeterminado es solo compra; para enviar órdenes de venta, debes activarlo con "true". Aplica no solo a la creación sino también a la modificación (modificar una orden de venta requiere que la venta esté permitida). La cancelación de órdenes ya enviadas siempre es posible.

`TOSSINVEST_ALLOW_MARKET_ORDERS` (predeterminado: `false`)

Indica si se permiten órdenes de mercado (MARKET). El valor predeterminado es bloquear órdenes de mercado (solo se permiten órdenes limitadas LIMIT, donde tú fijas el precio). Las órdenes de mercado pueden ejecutarse a precios menos favorables de lo esperado, por lo que están desactivadas de forma conservadora. Si necesitas órdenes de mercado, actívalas con "true". Este bloqueo también aplica a la modificación: si el mercado está desactivado, no se puede cambiar una orden limitada a una de mercado mediante modificación.

`TOSSINVEST_MARKET_ORDER_BUFFER_PCT` (predeterminado: `5`)

Porcentaje de buffer adicional que se suma a la cotización actual al calcular el monto estimado de una compra de mercado. Es para verificar el límite de monto de forma conservadora (estimando un poco más alto). Ejemplo: con 5, se verifica el límite usando un 5% por encima de la cotización. Solo tiene sentido cuando las órdenes de mercado están activadas.

`TOSSINVEST_LOCK_ACCOUNT` (predeterminado: `true`)

Bloquea si el accountSeq en la solicitud de orden es diferente de la cuenta predeterminada (TOSSINVEST_ACCOUNT). Evita que las órdenes se envíen por error a otra cuenta. Si necesitas operar entre varias cuentas, desactívalo con "false".

`TOSSINVEST_GUARD_STATE_PATH` (predeterminado: carpeta de datos del SO)

Ruta del archivo donde se guarda el acumulado del límite diario. Normalmente no necesitas preocuparte por esto (si no se configura, usa tossinvest-mcp/guard-state.json en la carpeta de datos del SO). Si ejecutas varias instancias de este MCP simultáneamente en la misma computadora, asigna una ruta diferente para cada instancia (ver "Uso de múltiples instancias" a continuación).

Configuración recomendada al activar el trading por primera vez

Al activar el trading por primera vez, se recomienda establecer límites pequeños. A continuación se muestra un ejemplo conservador: "solo acciones nacionales, solo instrumentos predefinidos, solo órdenes limitadas, con límites de monto por orden, diario y número de órdenes".

{
  "mcpServers": {
    "tossinvest": {
      "command": "npx",
      "args": ["tossinvest-mcp"],
      "env": {
        "TOSSINVEST_API_KEY": "발급받은-API-Key",
        "TOSSINVEST_SECRET_KEY": "발급받은-Secret-Key",
        "TOSSINVEST_ACCOUNT": "1",
        "TOSSINVEST_ENABLE_TRADING": "true",
        "TOSSINVEST_ALLOWED_SYMBOLS": "005930",
        "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "300000",
        "TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW": "1000000",
        "TOSSINVEST_DAILY_MAX_ORDER_COUNT": "5"
      }
    }
  }
}

En este ejemplo, la venta y la orden de mercado están desactivadas por defecto (false), por lo que solo se permite compra limitada de Samsung Electronics, con un máximo de 300,000 KRW por orden, 1,000,000 KRW por día y 5 órdenes por día. Una vez que te familiarices, amplía gradualmente los instrumentos y límites.

Notas:

Límites por moneda: Si solo configuras el límite en KRW, no se aplicarán límites de monto único/diario a las órdenes en USD (y viceversa). Si operas en ambas monedas, configura ambos límites.
Alcance del límite diario: Solo se registran y acumulan en el archivo de estado las órdenes exitosas a través de este MCP. No incluye otras actividades de la cuenta como la app de Toss (asume sesión única y MCP único).
Uso de múltiples instancias: La serialización del límite diario solo se garantiza dentro de un solo proceso. Si ejecutas varias instancias de este MCP simultáneamente con el mismo usuario del SO, la ruta del archivo de estado predeterminado será la misma y los acumulados se sobrescribirán entre sí, lo que puede desalinear los límites. Asigna rutas diferentes de TOSSINVEST_GUARD_STATE_PATH para cada instancia (límites independientes por instancia). Si varias instancias deben compartir el límite de una cuenta, se recomienda consolidarlas en una sola instancia.
Método de cálculo del límite diario: Las órdenes de creación y modificación se acumulan en el conteo/monto del día (una modificación cuenta como 1 orden nueva; de la orden original reemplazada solo se refleja el monto ejecutado). Las cancelaciones no se incluyen en el límite y siempre se permiten (para no bloquear la vía de reducción de riesgo). Si el límite diario de monto está activado, al verificar el límite se vuelven a consultar las órdenes pendientes del día mediante la API de Toss y se recalculan cada vez con 체결금액 + 미체결 잔량; las órdenes ejecutadas, canceladas, rechazadas o modificadas se reflejan de forma definitiva solo con el monto realmente ejecutado. Si falla la consulta de órdenes pendientes, se considera que no se puede verificar y se bloquean las nuevas órdenes. (Si solo está activado el límite de número, se decide solo con el conteo registrado del día sin esta reconsulta).
Bloqueo si no se puede estimar: Si no se puede determinar el precio, la cotización o la moneda, o si no se puede leer el archivo de estado, la orden se bloquea por seguridad. No se procede con suposiciones.
Protección contra demoras de respuesta: Si la API de Toss no responde en 20 segundos, la solicitud se interrumpe automáticamente, por lo que la herramienta no se queda detenida indefinidamente por problemas de red.
clientOrderId: Si no está en la entrada, se genera automáticamente con el prefijo tossinvest-mcp-YYYYMMDD-. Toss usa este valor como clave para evitar órdenes duplicadas durante 10 minutos.

Descripción de variables de entorno

Nombre	Obligatoria	Descripción
`TOSSINVEST_API_KEY`	Sí	API Key de la pantalla de Open API de Toss Securities
`TOSSINVEST_SECRET_KEY`	Sí	Secret Key de la pantalla de Open API de Toss Securities
`TOSSINVEST_ACCOUNT`	No	`accountSeq` de Toss Securities para usar por defecto. Si no se configura, `1`
`TOSSINVEST_BASE_URL`	No	Valor predeterminado: `https://openapi.tossinvest.com`
`TOSSINVEST_ENABLE_TRADING`	No	Solo si se configura como `true` se registran las herramientas de creación, modificación y cancelación de órdenes

Consulta la tabla de 거래 가드레일 anterior para las variables de entorno relacionadas con las protecciones de trading.

Solución de problemas

Aparece el mensaje de que no se encuentra el comando `node`

Node.js no está instalado o no está registrado en el PATH. Instala la versión LTS desde https://nodejs.org, abre una nueva terminal y vuelve a intentarlo.

Aparece el error `허용되지 않은 IP 주소입니다.`

La IP pública actual de tu computadora no está registrada en la lista de IPs permitidas de la Open API de Toss Securities.

Revisa el paso 설치방법 > 3. 허용 IP 등록 de este documento y registra la IP pública actual. La IP pública puede cambiar si cambias de red (casa, oficina, cafetería, VPN, etc.).

Las herramientas no aparecen en el cliente MCP

Verifica que la sintaxis JSON de la configuración sea correcta y cierra completamente el cliente MCP antes de volver a ejecutarlo. Si TOSSINVEST_API_KEY y TOSSINVEST_SECRET_KEY están vacíos, el servidor no se iniciará.

La consulta de cuentas funciona, pero la consulta de acciones en cartera falla

Las funciones relacionadas con la cuenta (acciones en cartera, órdenes, monto disponible para compra) requieren accountSeq. Este programa usa por defecto 1. Si necesitas usar otro accountSeq según el resultado de la consulta de lista de cuentas, cambia TOSSINVEST_ACCOUNT a ese valor y vuelve a ejecutarlo.

Las herramientas de orden no aparecen

Es normal. Por defecto, las herramientas de orden no están registradas. Para permitir trading real, debes configurar TOSSINVEST_ENABLE_TRADING como true.

Configuré `TOSSINVEST_ENABLE_TRADING` como `true` pero las órdenes no funcionan

Aunque las herramientas de orden aparezcan, en la configuración predeterminada cada solicitud de orden requiere confirmOrderAction: true.

Al solicitar una orden a la IA, indícale explícitamente que incluya el valor de confirmación como se muestra a continuación.

실제 주문 실행을 확인하며 confirmOrderAction 값을 true로 넣어줘.

Si es difícil ingresar este valor cada vez (como en automatización), puedes desactivar solo el requisito de confirmación con TOSSINVEST_REQUIRE_ORDER_CONFIRMATION=false. En ese caso, las demás protecciones activadas (monto, diario, venta, mercado, etc.) siguen aplicándose.

Después de modificar una orden, la consulta con el orderId anterior muestra resultados extraños

La modificación de órdenes de Toss Securities devuelve un nuevo orderId. Usa el nuevo orderId de la respuesta de modificación.

Todas las órdenes se bloquean con el error "cannot reconcile open order ..."

Si el límite diario de monto está activado, antes de una nueva orden se consulta el estado actual de las órdenes pendientes del día mediante la API de Toss para recalcular el límite. Si esta consulta falla, se considera que no se puede verificar y las órdenes se bloquean por seguridad (no se procede con suposiciones). Si es un problema temporal de red/límite (429), reintentar después de un momento lo resolverá. Si quedan órdenes que ya no se consultan en el archivo de estado y el bloqueo continúa, en un momento sin operaciones puedes hacer una copia de seguridad del archivo de estado (ruta TOSSINVEST_GUARD_STATE_PATH; si no se configura, tossinvest-mcp/guard-state.json en la carpeta de datos del SO) y eliminarlo para reiniciar el acumulado del día (solo desaparece el acumulado de órdenes del día colocadas con este MCP; no afecta las órdenes reales).

Las órdenes se bloquean con el mensaje `Order blocked: ...`

En la mayoría de los casos es un bloqueo intencional por una protección configurada. Identifica la causa con las palabras clave del mensaje (ver 오류 및 차단 메시지 목록 a continuación). Ejemplo: ... amount ... exceeds the per-order limit indica que se superó el límite de monto por orden, daily ... limit reached indica que se alcanzó el límite diario, ... is not in TOSSINVEST_ALLOWED_SYMBOLS indica un instrumento fuera de la lista permitida. Si el límite es demasiado estricto, ajusta la variable de entorno correspondiente.

Las órdenes de venta (o de mercado) no funcionan

Por defecto, la venta y la orden de mercado están desactivadas. La venta se activa con TOSSINVEST_ALLOW_SELL_ORDERS=true y la orden de mercado con TOSSINVEST_ALLOW_MARKET_ORDERS=true. Este bloqueo también aplica a la modificación: si están desactivadas, no se pueden crear órdenes de venta/mercado ni siquiera mediante modificación.

Las órdenes se bloquean aunque parece que no superé el límite diario

El límite diario solo acumula las órdenes colocadas con este MCP, e incluye tanto la creación como la modificación (una modificación cuenta como 1 orden nueva). Si modificaste varias veces, el número puede aumentar rápidamente. Además, las órdenes pendientes se calculan de forma conservadora con 체결금액 + 미체결 잔량. Consulta "Método de cálculo del límite diario" en 거래 가드레일 para las reglas detalladas.

La respuesta incluye `_guardStateWarning`

Si ves _guardStateWarning, la orden en sí ya fue exitosa. Sin embargo, es una advertencia de que algunos registros internos necesarios para el acumulado del límite diario podrían faltar. No vuelvas a enviar la orden bajo ninguna circunstancia (riesgo de orden duplicada). La orden enviada se puede verificar con la consulta de lista/detalle de órdenes.

Lista de mensajes de error y bloqueo

Estos son los principales mensajes que este programa puede emitir y su significado. Los mensajes que comienzan con Order blocked: son bloqueos realizados antes de que la orden se envíe a Toss por seguridad (la orden real no se envió).

1) Mensajes de bloqueo de órdenes (protecciones) — `Order blocked: ...`

Palabra clave del mensaje	Significado	Solución
`confirmOrderAction=true is required`	Falta el valor de confirmación de la orden	Agregar `confirmOrderAction: true` a la solicitud (o `TOSSINVEST_REQUIRE_ORDER_CONFIRMATION=false`)
`account is locked to TOSSINVEST_ACCOUNT (...)`	Orden con una cuenta diferente a la cuenta base bloqueada	Realizar la orden con la cuenta base o `TOSSINVEST_LOCK_ACCOUNT=false`
`sell orders are disabled`	Venta desactivada	`TOSSINVEST_ALLOW_SELL_ORDERS=true`
`market orders are disabled`	Orden de mercado desactivada	`TOSSINVEST_ALLOW_MARKET_ORDERS=true`
`... is not in TOSSINVEST_ALLOWED_SYMBOLS`	Instrumento fuera de la lista permitida	Agregar a la lista permitida o cambiar de instrumento
`estimated amount ... exceeds the per-order limit`	Límite de monto por orden superado	Reducir cantidad/precio o aumentar el límite
`daily order count limit reached (n/m)`	Límite diario de número de órdenes alcanzado	Esperar al reinicio del día siguiente (KST) o aumentar el límite
`daily KRW/USD amount limit reached`	Límite diario de monto acumulado alcanzado	Igual que el anterior
`국내 주식 주문 정정은 수량(quantity) 정정이 필수`	Falta la cantidad en la corrección KR	Especificar `quantity`
`미국 주식 주문 정정은 수량(quantity) 정정을 지원하지 않으며`	Cantidad enviada en la corrección US	Quitar `quantity` e ingresar solo `price`
`시장가(MARKET) 주문 정정에는 가격(price)을 전달할 수 없습니다`	Precio enviado en la corrección de mercado	Quitar `price` y corregir
`지정가(LIMIT) 주문 정정에는 가격(price)이 필수`	No se puede verificar el precio de la corrección limitada	Especificar `price`
`cannot determine the currency/order type/side/symbol of order ...`	No se puede verificar la información de la orden a corregir	Verificar que `orderId` sea correcto y reintentar después (no proceder con suposiciones)
`cannot estimate ... amount` / `best ask/bid unavailable` / `did not report a recognized currency` / `could not read a recognized currency`	No se puede confirmar precio, cotización o moneda	Verificar que haya cotizaciones durante la sesión y reintentar (especialmente las órdenes de mercado necesitan cotización)
`cannot reconcile open order ... against the daily limit`	Fallo al consultar el estado de órdenes pendientes	Consultar el elemento "cannot reconcile open order" anterior
`cannot read guard state file` / `is not valid JSON` / `must contain a JSON array`	Archivo de estado dañado/fallo de lectura	Hacer copia de seguridad del archivo de estado y eliminarlo (consultar la ruta en el elemento reconcile anterior)

2) Errores de la API de Toss (códigos/estados de respuesta)

Mensaje/Código	Significado	Solución
`허용되지 않은 IP 주소입니다.`	IP pública no registrada	Registrar la IP pública actual en la lista permitida según el paso 3 de la instalación
HTTP 401 / `invalid-token`	Error de clave o clave desactivada	Verificar `API Key`/`Secret Key` y el estado activo de la clave
HTTP 429	Límite de solicitudes superado	Reintentar después (el programa reintenta automáticamente en algunos casos)
`account-header-required`	Se necesita información de la cuenta	Verificar `TOSSINVEST_ACCOUNT` o el `accountSeq` de la solicitud
`confirm-high-value-required`	Se requiere confirmación para órdenes de alto monto	Reconfirmar el monto e incluir `confirmHighValueOrder: true` en la entrada de la orden

3) Errores de red/conexión

Mensaje	Significado	Solución
`Failed to connect to Toss Open API.`	Fallo de conexión	Verificar internet, DNS, VPN, firewall y `TOSSINVEST_BASE_URL`
`Toss Open API request timed out after 20s.`	Respuesta retrasada (más de 20 segundos)	Verificar el estado de la red y reintentar
`Invalid OAuth token response` / `OAuth token request failed (...)`	Fallo en la emisión del token	Verificar la clave y reintentar después

4) Orden exitosa pero con advertencias

Si la respuesta contiene el campo _guardStateWarning, la orden se envió y se aceptó correctamente. Es solo una advertencia de que algunos registros del límite interno pudieron omitirse; no vuelva a realizar la orden y verifique el estado en la lista de órdenes.

Cambios (0.2.0)

La versión 0.2.0 refuerza significativamente las salvaguardas de trading. Cambios principales:

Eliminación de la opción TOSSINVEST_YOLO_TRADING → reemplazada por barreras de protección de trading más detalladas. Límites de monto por orden/día, límite diario de número de órdenes, lista permitida de instrumentos, bloqueo de venta/mercado y bloqueo de cuenta se pueden activar por separado. (Consultar 거래 가드레일 arriba)
Sistema de valor de confirmación de órdenes: por defecto, se exige confirmOrderAction: true en todas las órdenes para evitar que la IA envíe órdenes por error.
Recálculo del límite diario según el estado real de las órdenes: se vuelven a consultar las órdenes pendientes en Toss para reflejar con precisión correcciones y cancelaciones.
Reglas de corrección de órdenes reforzadas: se refleja que la corrección reemplaza la orden original y devuelve un nuevo orderId, y se validan las reglas de entrada para domésticas/EE. UU. y limitadas/mercado antes de la orden. Las correcciones también están sujetas a bloqueo de venta/mercado, lista permitida de instrumentos y límites de monto/número, igual que la creación (no se pueden evadir las barreras con correcciones).
Mejoras de estabilidad: timeout de 20 segundos en solicitudes API, mejores mensajes de error de token OAuth y preservación de la respuesta de éxito de la orden con solo una advertencia adjunta si falla el registro de la orden.

Para un historial detallado de cambios internos, consulte el historial de commits de git.

Para desarrolladores

Para clonar este repositorio y desarrollar directamente:

npm install
npm run typecheck
npm test
npm run build

Para probar el flujo de herramientas de órdenes con un servidor mock sin órdenes reales:

npm run smoke:trading:mock

Descargo de responsabilidad

Este programa es una herramienta que conecta la API abierta de Toss Securities para su uso en MCP. No proporciona asesoramiento de inversión, recomendaciones de inversión, sugerencias de compra/venta ni servicios de garantía de rendimiento.

La información consultada mediante este programa, las respuestas generadas por IA y las órdenes sugeridas por IA pueden ser inexactas, estar desactualizadas o diferir de la intención del usuario. Toda decisión de inversión, ejecución de órdenes y el uso del programa son responsabilidad final del usuario.

Si activa las funciones de trading y utiliza las herramientas de creación, corrección o cancelación de órdenes, se pueden enviar órdenes reales a una cuenta real. Verifique siempre directamente el instrumento, precio, cantidad, tipo de orden y cuenta antes de realizar una orden.

Este proyecto está actualmente en desarrollo; los desarrolladores y distribuidores de este proyecto no se hacen responsables de pérdidas de inversión, errores de órdenes, fallos de API, errores de datos, mal funcionamiento del cliente o errores de respuesta de IA derivados del uso de este programa.

Licencia

Licencia MIT

Otros

Documentación oficial de la API abierta de Toss Securities: https://developers.tossinvest.com/docs

Se declara que se utilizó asistencia de IA generativa para algunas tareas, como la redacción del archivo README.md.

tossinvest-mcp

Documentación

tossinvest-mcp

Resumen del programa

Advertencia más importante

Funciones y características disponibles con el programa

Método de instalación

1. Verificar la instalación de Node.js

2. Preparar la API Key de la Open API de Toss Securities

3. Registrar la IP permitida

4. Registro en el cliente MCP

5. Verificación del número de cuenta

6. Prueba de las funciones de consulta

Activar las funciones de trading

Cómo ingresar confirmOrderAction como true

Ejecutar órdenes sin valor de confirmación (automatización)

Protecciones de trading (guardrails)

Resumen rápido (tabla)

Descripción detallada por opción

TOSSINVEST_REQUIRE_ORDER_CONFIRMATION (predeterminado: true)

TOSSINVEST_MAX_ORDER_AMOUNT_KRW (predeterminado: ninguno)

TOSSINVEST_MAX_ORDER_AMOUNT_USD (predeterminado: ninguno)

TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW (predeterminado: ninguno)

TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD (predeterminado: ninguno)

TOSSINVEST_DAILY_MAX_ORDER_COUNT (predeterminado: ninguno)

TOSSINVEST_ALLOWED_SYMBOLS (predeterminado: ninguno)

TOSSINVEST_ALLOW_SELL_ORDERS (predeterminado: false)

TOSSINVEST_ALLOW_MARKET_ORDERS (predeterminado: false)

TOSSINVEST_MARKET_ORDER_BUFFER_PCT (predeterminado: 5)

TOSSINVEST_LOCK_ACCOUNT (predeterminado: true)

TOSSINVEST_GUARD_STATE_PATH (predeterminado: carpeta de datos del SO)

Configuración recomendada al activar el trading por primera vez

Descripción de variables de entorno

Solución de problemas

Aparece el mensaje de que no se encuentra el comando node

Aparece el error 허용되지 않은 IP 주소입니다.

Las herramientas no aparecen en el cliente MCP

La consulta de cuentas funciona, pero la consulta de acciones en cartera falla

Las herramientas de orden no aparecen

Configuré TOSSINVEST_ENABLE_TRADING como true pero las órdenes no funcionan

Después de modificar una orden, la consulta con el orderId anterior muestra resultados extraños

Todas las órdenes se bloquean con el error "cannot reconcile open order ..."

Las órdenes se bloquean con el mensaje Order blocked: ...

Las órdenes de venta (o de mercado) no funcionan

Las órdenes se bloquean aunque parece que no superé el límite diario

La respuesta incluye _guardStateWarning

Lista de mensajes de error y bloqueo

1) Mensajes de bloqueo de órdenes (protecciones) — Order blocked: ...

2) Errores de la API de Toss (códigos/estados de respuesta)

3) Errores de red/conexión

4) Orden exitosa pero con advertencias

Cambios (0.2.0)

Para desarrolladores

Descargo de responsabilidad

Licencia

Otros

Cómo ingresar `confirmOrderAction` como true

`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION` (predeterminado: `true`)

`TOSSINVEST_MAX_ORDER_AMOUNT_KRW` (predeterminado: ninguno)

`TOSSINVEST_MAX_ORDER_AMOUNT_USD` (predeterminado: ninguno)

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` (predeterminado: ninguno)

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` (predeterminado: ninguno)

`TOSSINVEST_DAILY_MAX_ORDER_COUNT` (predeterminado: ninguno)

`TOSSINVEST_ALLOWED_SYMBOLS` (predeterminado: ninguno)

`TOSSINVEST_ALLOW_SELL_ORDERS` (predeterminado: `false`)

`TOSSINVEST_ALLOW_MARKET_ORDERS` (predeterminado: `false`)

`TOSSINVEST_MARKET_ORDER_BUFFER_PCT` (predeterminado: `5`)

`TOSSINVEST_LOCK_ACCOUNT` (predeterminado: `true`)

`TOSSINVEST_GUARD_STATE_PATH` (predeterminado: carpeta de datos del SO)

Aparece el mensaje de que no se encuentra el comando `node`

Aparece el error `허용되지 않은 IP 주소입니다.`

Configuré `TOSSINVEST_ENABLE_TRADING` como `true` pero las órdenes no funcionan

Las órdenes se bloquean con el mensaje `Order blocked: ...`

La respuesta incluye `_guardStateWarning`

1) Mensajes de bloqueo de órdenes (protecciones) — `Order blocked: ...`