tossinvest-mcp

MCP 서버 que utiliza a Open API da Toss Securities para fornecer funcionalidades como cotação em tempo real, ordem de compra e venda, candles, ações em carteira, saldo disponível para compra, e criação, alteração e cancelamento de ordens.

GitHub

Experimente este MCPPatrocinado

Documentação

tossinvest-mcp

Visão geral do programa

tossinvest-mcp é um servidor MCP local que permite usar a Open API da Toss Securities (consulta de preços atuais, ordens, consulta de saldo, etc.) em aplicativos compatíveis com MCP, como serviços OpenAI, Claude Desktop e Cursor.

Em outras palavras, ao registrar este programa em um cliente MCP, você pode fazer solicitações à IA como as seguintes:

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

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

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

Este programa é executado apenas no seu computador.

Aviso mais importante

A Open API da Toss Securities não possui ambiente de sandbox ou simulação de investimentos.

Se você ativar os recursos de negociação, poderá criar, alterar e cancelar ordens reais em uma conta real. Ao usar pela primeira vez, certifique-se de NÃO ativar os recursos de negociação e comece verificando os recursos de consulta.

Na configuração padrão, as ferramentas de criação, alteração e cancelamento de ordens não são registradas.

Recursos e características do programa

Mesmo sem ativar os recursos de negociação, você pode usar os seguintes recursos:

Consulta de preços atuais de ações domésticas/americanas
Consulta do livro de ofertas
Consulta de negociações recentes
Consulta de gráfico de candles
Consulta de limite de alta/baixa
Consulta de informações básicas do ativo
Consulta de avisos de compra
Consulta de taxa de câmbio
Consulta de horário de funcionamento dos mercados doméstico/americano
Consulta de lista de contas
Consulta de ações em carteira
Consulta de valor disponível para compra
Consulta de quantidade disponível para venda
Consulta de taxas de negociação
Consulta de lista de ordens
Consulta de detalhes de ordens

Ferramentas disponíveis quando os recursos de negociação estão ativados:

toss_create_order: criação de ordem
toss_modify_order: alteração de ordem
toss_cancel_order: cancelamento de ordem

Características:

Executado com npx tossinvest-mcp, portanto o processo de instalação é curto.
A API Key e a Secret Key são passadas por variáveis de ambiente.
O token OAuth é emitido automaticamente internamente e renovado automaticamente 60 segundos antes da expiração.
Os recursos que exigem conta usam, por padrão, a conta nº 1 da accountSeq.
Se você tiver várias contas ou quiser usar outra conta, pode alterar pelo valor de TOSSINVEST_ACCOUNT.
Os recursos de criação, alteração e cancelamento de ordens estão desativados por padrão.
Mesmo com os recursos de negociação ativados, no padrão, a API de ordens não é chamada sem o valor de confirmação confirmOrderAction: true.
Limites de ordem, bloqueio de venda/ordem a mercado, lista de ativos permitidos e limites diários podem ser ativados por variáveis de ambiente, e todas as verificações são aplicadas no servidor antes da chamada à API de ordens da Toss Securities. (Veja 거래 가드레일 abaixo)

Importante: toss_modify_order não é um simples PATCH que modifica a ordem existente no local. A API da Toss Securities processa substituindo a ordem original e retorna um novo orderId após a alteração. Use o novo orderId para consulta de detalhes da ordem, nova alteração ou cancelamento.

Instalação

Siga os passos abaixo na ordem.

1. Verificar a instalação do Node.js

Abra o terminal ou PowerShell e digite o comando abaixo.

node -v

Se aparecer v20 ou superior, prossiga para o próximo passo.

Se o Node.js não estiver instalado ou a versão for antiga, instale a versão LTS em https://nodejs.org e abra um novo terminal para verificar novamente.

2. Preparar a Open API Key da Toss Securities

Faça login no WTS da Toss Securities e acesse a tela de configuração da Open API.

Nessa tela, emita e guarde os seguintes valores:

API Key
Secret Key

Esses dois valores devem ser inseridos na configuração do MCP. Não os compartilhe com outras pessoas.

3. Registrar o IP permitido

A Open API da Toss Securities só pode ser chamada a partir de IPs permitidos. Se essa configuração estiver ausente, ocorrerá um erro como 허용되지 않은 IP 주소입니다..

Primeiro, verifique o IP público atual do seu computador. Use o comando abaixo.

PowerShell (Windows):

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

Terminal macOS ou Linux:

curl https://api.ipify.org

Adicione o endereço IP obtido à lista de IPs permitidos na tela de configuração da Open API no WTS da Toss Securities.

Fluxo aproximado:

Faça login no WTS da Toss Securities.
Vá para o menu Configurações - Open API.
Encontre a área de gerenciamento de IPs permitidos.
Adicione o IP público verificado acima.

4. Registrar no cliente MCP

Adicione o seguinte conteúdo ao arquivo de configuração do cliente MCP ou à tela de configuração de Servidores MCP.

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

Após a configuração, feche completamente o cliente MCP e execute-o novamente.

Na primeira execução, o npm baixará automaticamente o pacote tossinvest-mcp.

5. Verificar o número da conta

No início, não é necessário inserir TOSSINVEST_ACCOUNT. Este programa usa, por padrão, a conta nº 1 da accountSeq.

No entanto, se você tiver várias contas ou quiser confirmar se a conta nº 1 é a correta, consulte a lista de contas.

No cliente MCP, faça a seguinte solicitação.

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

Na resposta, encontre o valor de accountSeq. Se quiser usar outra conta como conta padrão, adicione ou altere o valor abaixo na configuração.

"TOSSINVEST_ACCOUNT": "1"

Por exemplo, se quiser usar uma conta cujo accountSeq seja 2, configure assim.

"TOSSINVEST_ACCOUNT": "2"

Um exemplo completo com número de conta explícito é o seguinte.

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

Se TOSSINVEST_ACCOUNT não for configurado, o valor padrão 1 será usado. Se configurado, essa conta será usada como padrão em recursos que exigem conta, como ações em carteira, lista de ordens e valor disponível para compra.

6. Testar os recursos de consulta

No cliente MCP, tente fazer as seguintes solicitações.

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

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

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

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

Ativando os recursos de negociação

Verifique novamente. A Open API da Toss Securities não possui sandbox. Ativar os recursos de negociação pode enviar ordens reais.

Para usar os recursos de negociação, adicione o seguinte valor a env na configuração do MCP.

"TOSSINVEST_ENABLE_TRADING": "true"

Exemplo 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"
      }
    }
  }
}

Mesmo com os recursos de negociação ativados, as ferramentas de ordem não são executadas sem um valor de confirmação adicional. As ferramentas de criação, alteração e cancelamento de ordens só chamam a API da Toss Securities se a solicitação incluir confirmOrderAction: true.

Como inserir `confirmOrderAction` como true

confirmOrderAction não é uma variável de ambiente da configuração do MCP. É um valor de entrada da solicitação de ordem que deve estar presente em cada chamada das ferramentas de criação, alteração e cancelamento de ordens.

Por exemplo, a entrada real da ferramenta de criação de ordem tem esta forma.

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

Ao fazer solicitações em linguagem natural no cliente MCP, é recomendável ser explícito, como abaixo.

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

O mesmo vale para alteração e cancelamento.

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

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

Dependendo do cliente, um botão de aprovação ou janela de confirmação pode ser exibido antes da execução da ferramenta de ordem. Nesse caso, confirmOrderAction: true também deve estar incluído na entrada da ferramenta de ordem.

Executar ordens sem valor de confirmação (automação)

Nota: a opção TOSSINVEST_YOLO_TRADING de versões anteriores foi removida. Mesmo desativando o valor de confirmação, os demais guardrails continuam aplicados.

Se for difícil inserir confirmOrderAction: true a cada vez, como em ambientes de automação, você pode desativar apenas a exigência de confirmação.

"TOSSINVEST_REQUIRE_ORDER_CONFIRMATION": "false"

Com esse valor desativado, as ordens podem ser enviadas sem confirmOrderAction, mas os demais guardrails ativados, como limite de ordem, bloqueio de venda/ordem a mercado, lista de ativos permitidos e limite diário, continuam valendo. É fortemente recomendado configurar limites de valor/limite diário antes de desativar o valor de confirmação.

Guardrails de negociação

Os guardrails são mecanismos de segurança que impedem que a IA envie ordens por engano, ou ordens muito grandes/frequentes. Todas as verificações são feitas dentro deste programa antes de a ordem chegar ao servidor da Toss Securities, portanto ordens que excedam os limites não são enviadas à Toss.

Todas as opções são ativadas adicionando uma linha por vez em env na configuração do MCP; opções não ativadas não são aplicadas (o padrão é conservador). Todos os valores são informados como strings. Exemplo: "TOSSINVEST_MAX_ORDER_AMOUNT_KRW": "500000".

Visão geral (tabela resumo)

Nome	Padrão	Descrição resumida
`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION`	`true`	Exige valor de confirmação `confirmOrderAction: true` para cada ordem
`TOSSINVEST_MAX_ORDER_AMOUNT_KRW`	Nenhum	Limite de valor por ordem (KRW)
`TOSSINVEST_MAX_ORDER_AMOUNT_USD`	Nenhum	Limite de valor por ordem (USD)
`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW`	Nenhum	Limite de valor acumulado diário (KRW)
`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD`	Nenhum	Limite de valor acumulado diário (USD)
`TOSSINVEST_DAILY_MAX_ORDER_COUNT`	Nenhum	Limite de número de ordens por dia
`TOSSINVEST_ALLOWED_SYMBOLS`	Nenhum	Apenas ativos permitidos (whitelist)
`TOSSINVEST_ALLOW_SELL_ORDERS`	`false`	Permite ordens de venda
`TOSSINVEST_ALLOW_MARKET_ORDERS`	`false`	Permite ordens a mercado
`TOSSINVEST_MARKET_ORDER_BUFFER_PCT`	`5`	Buffer de margem (%) para cálculo do limite a mercado
`TOSSINVEST_LOCK_ACCOUNT`	`true`	Bloqueia ordens apenas na conta padrão configurada
`TOSSINVEST_GUARD_STATE_PATH`	Pasta de dados do SO	Caminho do arquivo de armazenamento do limite diário

Descrição detalhada por opção

`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION` (padrão: `true`)

Para criar, alterar ou cancelar ordens, a solicitação deve conter confirmOrderAction: true para que seja realmente enviada à Toss. É o mecanismo de segurança mais básico para impedir que a IA envie ordens por engano durante uma conversa. Se for difícil inserir o valor de confirmação a cada vez, como em automação, pode ser desativado com "false", mas mesmo desativado, os limites de valor, quantidade, ativos e venda/mercado abaixo continuam valendo. Antes de desativar, é fortemente recomendado configurar limites de valor e diários.

`TOSSINVEST_MAX_ORDER_AMOUNT_KRW` (padrão: nenhum)

Limite de valor para uma única ordem em KRW. Se o valor estimado da ordem (para ordem limitada: quantidade × preço; para ordem a mercado: preço de oferta + buffer) exceder esse valor, a ordem é bloqueada. Exemplo: "500000" → bloqueia ordens em KRW acima de 500.000 won por vez. Se não configurado, não há limite de valor por ordem.

`TOSSINVEST_MAX_ORDER_AMOUNT_USD` (padrão: nenhum)

Limite de valor para uma única ordem de ações americanas (USD). Exemplo: "1000" → bloqueia ordens acima de US$ 1.000 por vez. Não há conversão entre KRW e USD. O limite em KRW se aplica apenas a ordens em KRW, e o limite em USD apenas a ordens em USD; portanto, se você negociar nos dois mercados, configure ambos os limites.

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` (padrão: nenhum)

Limite acumulado do valor de ordens em KRW enviadas por este programa em um dia (horário da Coreia, reiniciado à meia-noite). Exemplo: "2000000" → permite até 2 milhões de won por dia. Ordens alteradas também são contabilizadas no acumulado; cancelamentos não são contabilizados (veja "Método de cálculo do limite diário" abaixo).

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` (padrão: nenhum)

Versão em dólar do item acima. Limite de valor acumulado diário de ordens em USD.

`TOSSINVEST_DAILY_MAX_ORDER_COUNT` (padrão: nenhum)

Limite do número de ordens por dia. Exemplo: "10" → até 10 ordens por dia. Alterações contam como 1 nova ordem. Cancelamentos não são contabilizados. Útil para evitar negociações excessivamente frequentes.

`TOSSINVEST_ALLOWED_SYMBOLS` (padrão: nenhum)

Lista separada por vírgulas dos únicos ativos permitidos para negociação. Ordens de ativos fora da lista são bloqueadas (tanto criação quanto alteração). Exemplo: "005930,AAPL,VOO" (Samsung Electronics, Apple, VOO). Para o mercado doméstico, use o código numérico de 6 dígitos; para o mercado americano, use o ticker. Se não configurado, todos os ativos são permitidos. Use quando quiser "negociar apenas ativos pré-definidos".

`TOSSINVEST_ALLOW_SELL_ORDERS` (padrão: `false`)

Permite ordens de venda. O padrão é apenas compra; para enviar ordens de venda, ative com "true". Aplica-se não apenas à criação, mas também à alteração (alterar uma ordem de venda exige que a venda esteja permitida). O cancelamento de ordens já enviadas é sempre permitido.

`TOSSINVEST_ALLOW_MARKET_ORDERS` (padrão: `false`)

Permite ordens a mercado (MARKET). O padrão é bloquear ordens a mercado (apenas ordens limitadas LIMIT, em que você define o preço, são permitidas). Ordens a mercado podem resultar em preço de execução pior que o esperado, por isso ficam desativadas por padrão. Se precisar de ordens a mercado, ative com "true". Esse bloqueio também se aplica à alteração: com ordens a mercado desativadas, não é possível alterar uma ordem limitada para ordem a mercado.

`TOSSINVEST_MARKET_ORDER_BUFFER_PCT` (padrão: `5`)

Buffer de margem (%) adicionado ao preço de oferta atual ao calcular o valor estimado de compra a mercado. Serve para verificar o limite de valor de forma conservadora (um pouco maior). Exemplo: com 5, o limite é verificado com 5% acima do preço de oferta. Só faz sentido quando ordens a mercado estão ativadas.

`TOSSINVEST_LOCK_ACCOUNT` (padrão: `true`)

Bloqueia se o accountSeq na solicitação de ordem for diferente da conta padrão (TOSSINVEST_ACCOUNT). Impede que ordens sejam enviadas por engano para outra conta. Se precisar negociar em várias contas, desative com "false".

`TOSSINVEST_GUARD_STATE_PATH` (padrão: pasta de dados do SO)

Caminho do arquivo que armazena o acumulado do limite diário. Normalmente não é necessário se preocupar (se não configurado, usa tossinvest-mcp/guard-state.json na pasta de dados do SO). Se você executar várias instâncias deste MCP simultaneamente no mesmo computador, defina caminhos diferentes para cada instância (veja "Ao usar várias instâncias" abaixo).

Configuração recomendada ao ativar a negociação pela primeira vez

Ao ativar a negociação pela primeira vez, é recomendável definir limites pequenos. Abaixo está um exemplo conservador de "apenas ações domésticas, apenas ativos pré-definidos, apenas ordem limitada, com limites de valor por ordem/dia e número de ordens".

{
  "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"
      }
    }
  }
}

Neste exemplo, venda e ordem a mercado estão desativadas por padrão (false), permitindo apenas compra limitada de Samsung Electronics, com limite de 300.000 won por ordem, 1 milhão de won por dia e até 5 ordens por dia. Depois de se familiarizar, amplie gradualmente os ativos e limites.

Observações:

Limites por moeda: se apenas o limite em KRW for configurado, ordens em USD não terão limite de valor por ordem/dia (e vice-versa). Se negociar nas duas moedas, configure ambos os limites.
Escopo do limite diário: apenas ordens bem-sucedidas por meio deste MCP são registradas e contabilizadas no arquivo de estado do guardrail. Outras atividades da conta, como no app da Toss, não são incluídas (premissa de sessão única/MCP único).
Ao usar várias instâncias: a serialização do limite diário é garantida apenas dentro de um único processo. Se você executar várias instâncias deste MCP simultaneamente com o mesmo usuário do SO, o caminho padrão do arquivo de estado será o mesmo, e os acumulados podem se sobrescrever, causando divergência nos limites. Defina TOSSINVEST_GUARD_STATE_PATH com caminhos diferentes para cada instância (limites independentes por instância). Se várias instâncias precisarem compartilhar o limite de uma conta, recomenda-se unificar em uma única instância.
Método de cálculo do limite diário: ordens de criação e alteração são contabilizadas no número/valor do dia (alteração conta como 1 nova ordem; a ordem original substituída reflete apenas o valor executado). Cancelamentos não são incluídos no limite e são sempre permitidos (para não bloquear o caminho de redução de risco). Se o limite diário de valor estiver ativado, na verificação do limite as ordens pendentes do dia são consultadas novamente na API da Toss e recalculadas a cada vez com 체결금액 + 미체결 잔량; ordens executadas, canceladas, rejeitadas ou com alteração concluída refletem apenas o valor realmente executado. Se a consulta de ordens pendentes falhar, considera-se impossível validar e novas ordens são bloqueadas. (Se apenas o limite de número estiver ativado, a decisão é baseada apenas no número registrado do dia, sem essa nova consulta.)
Bloqueio quando não é possível estimar: se preço, oferta ou moeda não puderem ser determinados, ou se o arquivo de estado não puder ser lido, a ordem é bloqueada por segurança. Não se prossegue com suposições.
Proteção contra atraso de resposta: solicitações à API da Toss são interrompidas automaticamente se não houver resposta em 20 segundos, evitando que a ferramenta fique travada indefinidamente por problemas de rede.
clientOrderId: se não estiver na entrada, é gerado automaticamente com o prefixo tossinvest-mcp-YYYYMMDD-. A Toss usa esse valor como chave de prevenção de ordens duplicadas por 10 minutos.

Descrição das variáveis de ambiente

Nome	Obrigatório	Descrição
`TOSSINVEST_API_KEY`	Sim	API Key da tela da Open API da Toss Securities
`TOSSINVEST_SECRET_KEY`	Sim	Secret Key da tela da Open API da Toss Securities
`TOSSINVEST_ACCOUNT`	Não	`accountSeq` da Toss Securities a ser usada por padrão. Se não configurado, `1`
`TOSSINVEST_BASE_URL`	Não	Valor padrão é `https://openapi.tossinvest.com`
`TOSSINVEST_ENABLE_TRADING`	Não	Deve ser definido como `true` para que as ferramentas de criação, alteração e cancelamento de ordens sejam registradas

Consulte a tabela 거래 가드레일 acima para as variáveis de ambiente relacionadas aos guardrails de negociação.

Solução de problemas

Erro: comando `node` não encontrado

O Node.js não está instalado ou não está registrado no PATH. Instale a versão LTS em https://nodejs.org, abra um novo terminal e tente novamente.

Erro: `허용되지 않은 IP 주소입니다.`

O IP público atual do seu computador não está registrado na lista de IPs permitidos da Open API da Toss Securities.

Verifique novamente a etapa 설치방법 > 3. 허용 IP 등록 deste documento e registre o IP público atual. O IP público pode mudar quando a rede mudar (casa, empresa, cafeteria, VPN etc.).

As ferramentas não aparecem no cliente MCP

Verifique se a sintaxe JSON da configuração está correta e feche completamente o cliente MCP antes de executá-lo novamente. Se TOSSINVEST_API_KEY e TOSSINVEST_SECRET_KEY estiverem vazios, o servidor não será iniciado.

A consulta de conta funciona, mas a consulta de ações em carteira falha

Recursos relacionados à conta, como ações em carteira, ordens e valor disponível para compra, exigem accountSeq. Este programa usa 1 por padrão. Se precisar usar outro accountSeq do resultado da consulta de lista de contas, altere TOSSINVEST_ACCOUNT para esse valor e execute novamente.

As ferramentas de ordem não aparecem

Isso é normal. Por padrão, as ferramentas de ordem não são registradas. Para permitir negociação real, defina TOSSINVEST_ENABLE_TRADING como true.

Configurei `TOSSINVEST_ENABLE_TRADING` como `true`, mas as ordens não funcionam

Mesmo que as ferramentas de ordem apareçam, na configuração padrão cada solicitação de ordem exige confirmOrderAction: true.

Ao solicitar uma ordem à IA, especifique explicitamente que o valor de confirmação deve ser incluído, como abaixo.

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

Se for difícil inserir esse valor a cada vez, como em ambientes de automação, você pode desativar apenas a exigência de confirmação com TOSSINVEST_REQUIRE_ORDER_CONFIRMATION=false. Nesse caso, os demais guardrails ativados, como limites de valor, diário, venda e mercado, continuam valendo.

Após alterar uma ordem, a consulta pelo orderId antigo mostra dados estranhos

A alteração de ordem da Toss Securities retorna um novo orderId. Use o novo orderId da resposta de alteração.

Erro "cannot reconcile open order ..." bloqueia todas as ordens

Se o limite diário de valor estiver ativado, antes de novas ordens o estado atual das ordens pendentes do dia é consultado na API da Toss para recalcular o limite. Se essa consulta falhar, considera-se impossível validar e as ordens são bloqueadas por segurança (não se prossegue com suposições). Se for um problema temporário de rede/limite (429), tente novamente mais tarde. Se ordens que não são mais encontradas permanecerem no arquivo de estado do guardrail e continuarem bloqueando, em um horário sem negociações, faça backup e exclua o arquivo de estado (caminho TOSSINVEST_GUARD_STATE_PATH; se não configurado, tossinvest-mcp/guard-state.json na pasta de dados do SO) para reiniciar o acumulado do dia (apenas o acumulado de ordens do dia enviadas por este MCP é removido; não afeta ordens reais).

Ordens bloqueadas com mensagem `Order blocked: ...`

Na maioria dos casos, é um bloqueio intencional por um guardrail configurado. Verifique as palavras-chave da mensagem para identificar a causa (veja 오류 및 차단 메시지 목록 abaixo). Exemplos: ... amount ... exceeds the per-order limit indica limite de valor por ordem excedido, daily ... limit reached indica limite diário atingido, ... is not in TOSSINVEST_ALLOWED_SYMBOLS indica ativo fora da lista permitida. Se os limites estiverem muito restritos, ajuste as variáveis de ambiente correspondentes.

Ordens de venda (ou a mercado) não funcionam

Por padrão, venda e ordem a mercado estão desativadas. A venda deve ser ativada com TOSSINVEST_ALLOW_SELL_ORDERS=true, e a ordem a mercado com TOSSINVEST_ALLOW_MARKET_ORDERS=true. Esse bloqueio também se aplica à alteração: com essas opções desativadas, não é possível criar ordens de venda ou a mercado nem mesmo por alteração.

Ordens bloqueadas mesmo sem ter excedido o limite diário

O limite diário contabiliza apenas ordens enviadas por este MCP, incluindo criação e alteração (alteração conta como 1 nova ordem). Se você alterou várias vezes, o número pode crescer rapidamente. Além disso, ordens pendentes são calculadas de forma conservadora com 체결금액 + 미체결 잔량. Consulte "Método de cálculo do limite diário" em 거래 가드레일 para regras detalhadas.

A resposta contém `_guardStateWarning`

Se _guardStateWarning aparecer, a ordem em si já foi bem-sucedida. É apenas um aviso de que parte do registro interno necessário para o acumulado do limite diário pode estar ausente. NUNCA envie a ordem novamente (risco de ordem duplicada). A ordem enviada pode ser verificada na consulta de lista/detalhes de ordens.

Lista de mensagens de erro e bloqueio

Principais mensagens que este programa pode emitir e seus significados. Mensagens que começam com Order blocked: indicam bloqueio antes de a ordem ser enviada à Toss, por segurança (nenhuma ordem real foi enviada).

1) Mensagens de bloqueio de ordem (guardrail) — `Order blocked: ...`

Palavra-chave da mensagem	Significado	Solução
`confirmOrderAction=true is required`	Valor de confirmação do pedido ausente	Adicione `confirmOrderAction: true` à solicitação (ou `TOSSINVEST_REQUIRE_ORDER_CONFIRMATION=false`)
`account is locked to TOSSINVEST_ACCOUNT (...)`	Pedido com conta diferente da conta padrão bloqueada	Faça o pedido com a conta padrão ou use `TOSSINVEST_LOCK_ACCOUNT=false`
`sell orders are disabled`	Venda desativada	Use `TOSSINVEST_ALLOW_SELL_ORDERS=true`
`market orders are disabled`	Ordem de mercado desativada	Use `TOSSINVEST_ALLOW_MARKET_ORDERS=true`
`... is not in TOSSINVEST_ALLOWED_SYMBOLS`	Ativo fora da lista de permitidos	Adicione à lista de permitidos ou mude o ativo
`estimated amount ... exceeds the per-order limit`	Limite de valor por pedido excedido	Reduza a quantidade/preço ou aumente o limite
`daily order count limit reached (n/m)`	Limite diário de número de pedidos atingido	Aguarde a reinicialização no dia seguinte (KST) ou aumente o limite
`daily KRW/USD amount limit reached`	Limite diário de valor acumulado atingido	Igual ao acima
`국내 주식 주문 정정은 수량(quantity) 정정이 필수`	Quantidade ausente na correção KR	Especifique `quantity`
`미국 주식 주문 정정은 수량(quantity) 정정을 지원하지 않으며`	Quantidade enviada na correção US	Remova `quantity` e insira apenas `price`
`시장가(MARKET) 주문 정정에는 가격(price)을 전달할 수 없습니다`	Preço enviado na correção de ordem de mercado	Remova `price` e corrija
`지정가(LIMIT) 주문 정정에는 가격(price)이 필수`	Preço da correção de ordem limitada não verificável	Especifique `price`
`cannot determine the currency/order type/side/symbol of order ...`	Informações do pedido a ser corrigido não verificáveis	Verifique se `orderId` está correto e tente novamente mais tarde (não prossiga com suposições)
`cannot estimate ... amount` / `best ask/bid unavailable` / `did not report a recognized currency` / `could not read a recognized currency`	Preço, cotação ou moeda não podem ser determinados	Verifique se há cotações durante o pregão e tente novamente (especialmente ordens de mercado precisam de cotações)
`cannot reconcile open order ... against the daily limit`	Falha ao consultar status de pedidos não preenchidos	Consulte o item "cannot reconcile open order" acima
`cannot read guard state file` / `is not valid JSON` / `must contain a JSON array`	Arquivo de estado corrompido/falha de leitura	Faça backup e exclua o arquivo de estado (consulte o caminho no item reconcile acima)

2) Erros da API Toss (código de resposta/status)

Mensagem/Código	Significado	Solução
`허용되지 않은 IP 주소입니다.`	IP público não registrado	Registre o IP público atual na lista de permitidos conforme o passo 3 da instalação
HTTP 401 / `invalid-token`	Erro de chave ou chave inativa	Verifique `API Key`/`Secret Key` e o status ativo da chave
HTTP 429	Limite de solicitações excedido	Tente novamente mais tarde (o programa faz algumas tentativas automáticas)
`account-header-required`	Informações da conta necessárias	Verifique `TOSSINVEST_ACCOUNT` ou o `accountSeq` da solicitação
`confirm-high-value-required`	Confirmação necessária para pedido de alto valor	Reconfirme o valor e adicione `confirmHighValueOrder: true` à entrada do pedido

3) Erros de rede/conexão

Mensagem	Significado	Solução
`Failed to connect to Toss Open API.`	Falha de conexão	Verifique internet, DNS, VPN, firewall e `TOSSINVEST_BASE_URL`
`Toss Open API request timed out after 20s.`	Resposta atrasada (mais de 20 segundos)	Verifique o estado da rede e tente novamente
`Invalid OAuth token response` / `OAuth token request failed (...)`	Falha na emissão do token	Verifique as chaves e tente novamente mais tarde

4) Pedido bem-sucedido, mas com avisos

Se a resposta contiver o campo _guardStateWarning, o pedido foi enviado e recebido normalmente. O aviso indica apenas que parte do registro interno de limites pode ter sido omitido. Não faça o pedido novamente; verifique o status na lista de pedidos.

Alterações (0.2.0)

A versão 0.2.0 reforça significativamente as proteções de negociação. Principais mudanças:

Remoção da opção TOSSINVEST_YOLO_TRADING → substituída por proteções de negociação mais detalhadas. Limites de valor por pedido/dia, limite diário de número de pedidos, lista de ativos permitidos, bloqueio de venda/ordem de mercado e bloqueio de conta podem ser ativados separadamente. (Consulte 거래 가드레일 acima)
Sistema de valor de confirmação de pedido: por padrão, todos os pedidos exigem confirmOrderAction: true, impedindo que a IA envie pedidos por engano.
Recálculo do limite diário com base no status real dos pedidos: consulta novamente os pedidos não preenchidos na Toss para refletir com precisão correções e cancelamentos.
Regras de correção de pedidos reforçadas: reflete que a correção substitui o pedido original e retorna um novo orderId, com validação das regras de entrada para doméstico/americano e ordem limitada/mercado antes do envio. Correções também estão sujeitas a bloqueio de venda/ordem de mercado, lista de ativos permitidos e limites de valor/número (não é possível contornar as proteções com correções).
Melhorias de estabilidade: timeout de 20 segundos para solicitações de API, mensagens de erro de token OAuth aprimoradas e preservação da resposta de sucesso do pedido com aviso anexado mesmo quando o registro do pedido falha.

Para o histórico detalhado de alterações internas, consulte o histórico de commits do git.

Para desenvolvedores

Para clonar este repositório e desenvolver diretamente:

npm install
npm run typecheck
npm test
npm run build

Para testar o fluxo das ferramentas de pedido com um servidor mock, sem pedidos reais:

npm run smoke:trading:mock

Aviso legal

Este programa é uma ferramenta que conecta a Open API da Toss Securities ao MCP. Não fornece consultoria de investimento, recomendações de investimento, sugestões de negociação ou serviços de garantia de lucro.

As informações consultadas, respostas geradas por IA e pedidos sugeridos pela IA por meio deste programa podem ser imprecisos, atrasados ou diferentes da intenção do usuário. Toda decisão de investimento, execução de pedidos e responsabilidade final pelo uso do programa são do usuário.

Se você ativar os recursos de negociação e usar as ferramentas de criação, correção e cancelamento de pedidos, pedidos reais podem ser enviados para sua conta real. Antes de enviar, verifique sempre o ativo, preço, quantidade, tipo de pedido e conta.

Este projeto está em desenvolvimento. Os desenvolvedores e distribuidores não se responsabilizam por perdas de investimento, erros de pedido, falhas de API, erros de dados, mau funcionamento do cliente ou erros de resposta da IA decorrentes do uso deste programa.

Licença

Licença MIT

Outros

Documentação oficial da Open API da Toss Securities: https://developers.tossinvest.com/docs

Informamos que parte do trabalho, como a criação do arquivo README.md, contou com a ajuda de IA generativa.

tossinvest-mcp

Documentação

tossinvest-mcp

Visão geral do programa

Aviso mais importante

Recursos e características do programa

Instalação

1. Verificar a instalação do Node.js

2. Preparar a Open API Key da Toss Securities

3. Registrar o IP permitido

4. Registrar no cliente MCP

5. Verificar o número da conta

6. Testar os recursos de consulta

Ativando os recursos de negociação

Como inserir confirmOrderAction como true

Executar ordens sem valor de confirmação (automação)

Guardrails de negociação

Visão geral (tabela resumo)

Descrição detalhada por opção

TOSSINVEST_REQUIRE_ORDER_CONFIRMATION (padrão: true)

TOSSINVEST_MAX_ORDER_AMOUNT_KRW (padrão: nenhum)

TOSSINVEST_MAX_ORDER_AMOUNT_USD (padrão: nenhum)

TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW (padrão: nenhum)

TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD (padrão: nenhum)

TOSSINVEST_DAILY_MAX_ORDER_COUNT (padrão: nenhum)

TOSSINVEST_ALLOWED_SYMBOLS (padrão: nenhum)

TOSSINVEST_ALLOW_SELL_ORDERS (padrão: false)

TOSSINVEST_ALLOW_MARKET_ORDERS (padrão: false)

TOSSINVEST_MARKET_ORDER_BUFFER_PCT (padrão: 5)

TOSSINVEST_LOCK_ACCOUNT (padrão: true)

TOSSINVEST_GUARD_STATE_PATH (padrão: pasta de dados do SO)

Configuração recomendada ao ativar a negociação pela primeira vez

Descrição das variáveis de ambiente

Solução de problemas

Erro: comando node não encontrado

Erro: 허용되지 않은 IP 주소입니다.

As ferramentas não aparecem no cliente MCP

A consulta de conta funciona, mas a consulta de ações em carteira falha

As ferramentas de ordem não aparecem

Configurei TOSSINVEST_ENABLE_TRADING como true, mas as ordens não funcionam

Após alterar uma ordem, a consulta pelo orderId antigo mostra dados estranhos

Erro "cannot reconcile open order ..." bloqueia todas as ordens

Ordens bloqueadas com mensagem Order blocked: ...

Ordens de venda (ou a mercado) não funcionam

Ordens bloqueadas mesmo sem ter excedido o limite diário

A resposta contém _guardStateWarning

Lista de mensagens de erro e bloqueio

1) Mensagens de bloqueio de ordem (guardrail) — Order blocked: ...

2) Erros da API Toss (código de resposta/status)

3) Erros de rede/conexão

4) Pedido bem-sucedido, mas com avisos

Alterações (0.2.0)

Para desenvolvedores

Aviso legal

Licença

Outros

Como inserir `confirmOrderAction` como true

`TOSSINVEST_REQUIRE_ORDER_CONFIRMATION` (padrão: `true`)

`TOSSINVEST_MAX_ORDER_AMOUNT_KRW` (padrão: nenhum)

`TOSSINVEST_MAX_ORDER_AMOUNT_USD` (padrão: nenhum)

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_KRW` (padrão: nenhum)

`TOSSINVEST_DAILY_MAX_ORDER_AMOUNT_USD` (padrão: nenhum)

`TOSSINVEST_DAILY_MAX_ORDER_COUNT` (padrão: nenhum)

`TOSSINVEST_ALLOWED_SYMBOLS` (padrão: nenhum)

`TOSSINVEST_ALLOW_SELL_ORDERS` (padrão: `false`)

`TOSSINVEST_ALLOW_MARKET_ORDERS` (padrão: `false`)

`TOSSINVEST_MARKET_ORDER_BUFFER_PCT` (padrão: `5`)

`TOSSINVEST_LOCK_ACCOUNT` (padrão: `true`)

`TOSSINVEST_GUARD_STATE_PATH` (padrão: pasta de dados do SO)

Erro: comando `node` não encontrado

Erro: `허용되지 않은 IP 주소입니다.`

Configurei `TOSSINVEST_ENABLE_TRADING` como `true`, mas as ordens não funcionam

Ordens bloqueadas com mensagem `Order blocked: ...`

A resposta contém `_guardStateWarning`

1) Mensagens de bloqueio de ordem (guardrail) — `Order blocked: ...`