Terminal MCP

Deixe a IA ver e interagir com seu terminal.

Terminal MCP dá aos LLMs uma visão compartilhada da sua sessão de terminal. Perfeito para depurar CLIs e aplicações TUI em tempo real, ou deixar a IA operar ferramentas baseadas em terminal de forma autônoma.

Instalação

npm install -g @ellery/terminal-mcp

Ou via script de instalação:

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

Configure suas ferramentas de IA

Conecte o terminal-mcp na configuração MCP de todas as ferramentas de IA instaladas na sua máquina de uma só vez:

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

Clientes suportados (cada um recebe o schema correto para seu formato de configuração):

Cliente	Arquivo de configuração	Formato
OpenAI Codex CLI	~/.codex/config.toml	TOML
GitHub Copilot CLI	~/.copilot/mcp-config.json	JSON
Gemini CLI	~/.gemini/settings.json	JSON
OpenCode	~/.config/opencode/opencode.json	JSON
Claude Code	~/.claude.json	JSON
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)	JSON

Um .bak de qualquer configuração pré-existente é gravado ao lado do original na primeira instalação. A entrada terminal-mcp é adicionada sem interferir em outros servidores ou chaves não relacionadas; executar setup novamente é uma operação sem efeito.

Atualização

npm install -g @ellery/terminal-mcp@latest

O modo interativo exibirá um banner no próximo lançamento quando uma versão mais recente estiver disponível — terminal-mcp verifica o registro npm uma vez por dia e armazena o resultado em cache. Os modos headless e cliente MCP nunca verificam ou exibem nada (mantendo o stdio MCP limpo). Para desativar completamente, defina NO_UPDATE_NOTIFIER=1 ou use --no-update-notifier.

Recursos

• Emulação Completa de Terminal: Usa xterm.js headless para emulação precisa de VT100/ANSI
• PTY Multiplataforma: Suporte nativo a pseudo-terminal via node-pty (macOS, Linux, Windows)
• Protocolo MCP: Implementa o Model Context Protocol para integração com assistentes de IA
• Gravação de Sessão: Grave sessões de terminal no formato asciicast para reprodução com asciinema
• API Simples: Nove ferramentas cobrindo entrada, observação, gravação e ciclo de vida da sessão
• Modo Headless: Execute como um servidor MCP autônomo sem TTY — ideal para CI, contêineres e ambientes não interativos
• Multi-Sessão: Execute múltiplas sessões de terminal isoladas em um único processo, identificadas por sessionId
• Modo Sandbox: Restrições de segurança opcionais para acesso a arquivos e rede

Compilação a partir do Código-Fonte

npm install
npm run build

Uso

Configuração MCP

Adicione às configurações do seu cliente MCP:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

Com opções personalizadas:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

Opções de Linha de Comando

terminal-mcp [OPTIONS]

Options:
  --cols <number>        Terminal width in columns (default: 120)
  --rows <number>        Terminal height in rows (default: 40)
  --shell <path>         Shell to use (default: $SHELL or bash)
  --headless             Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  --sandbox              Enable sandbox mode (restricts filesystem/network)
  --sandbox-config <path> Load sandbox config from JSON file
  --version, -v          Show version number
  --help, -h             Show help message

Recording Options:
  --record [mode]     Enable recording (default mode: always)
                      Modes: always, on-failure, off
  --record-dir <dir>  Recording output directory
                      (default: ~/.local/state/terminal-mcp/recordings)
  --idle-time-limit <sec>   Max idle time between events (default: 2s)
  --max-duration <sec>      Max recording duration (default: 3600s)
  --inactivity-timeout <sec>  Stop after no output (default: 600s)

Multi-Session Options:
  --max-sessions <n>           Max concurrent sessions (default: 5)
  --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
                               after this period (default: 600s)

Modo Headless

Por padrão, o Terminal MCP usa uma arquitetura de dois processos: você executa terminal-mcp em um terminal interativo (que cria um socket Unix), e então seu cliente MCP inicia uma segunda instância que se conecta a esse socket. Isso requer um TTY.

Modo headless (--headless) elimina esse requisito ao iniciar um PTY embutido internamente e servir MCP diretamente via stdio em um único processo. Sem sessão de terminal interativa, sem socket — apenas um servidor MCP autônomo com um terminal integrado.

Quando usar o modo headless

• Pipelines de CI/CD — sem TTY disponível
• Contêineres Docker — sem shell interativo para executar em paralelo
• Ambientes remotos/nuvem — servidores MCP iniciados por automação
• Configuração simplificada — processo único, sem coordenação de socket

Configuração

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--headless", "--cols", "120", "--rows", "40"]
    }
  }
}

Como funciona

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP Server (stdio transport)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

No modo headless, a sessão de terminal é inicializada imediatamente na inicialização, então todas as ferramentas (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession) estão disponíveis imediatamente.

Ferramentas MCP

Todas as ferramentas de entrada/saída (type, sendKey, getContent, takeScreenshot) aceitam um argumento opcional sessionId. Omita-o para usar a sessão padrão; passe o ID retornado por createSession para operar uma sessão específica.

type

Envia entrada de texto para o terminal.

{
  "name": "type",
  "arguments": {
    "text": "echo hello"
  }
}

sendKey

Envia teclas especiais ou combinações de teclas.

{
  "name": "sendKey",
  "arguments": {
    "key": "Enter"
  }
}

Teclas suportadas:

• Básicas: Enter, Tab, Escape, Backspace, Delete
• Setas: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• Navegação: Home, End, PageUp, PageDown, Insert
• Função: F1 até F12
• Controle: Ctrl+A até Ctrl+Z, Ctrl+C, Ctrl+D, etc.

getContent

Obtém o buffer do terminal como texto simples.

{
  "name": "getContent",
  "arguments": {
    "visibleOnly": false
  }
}

takeScreenshot

Captura o estado do terminal. Suporta três formatos de saída:

Formato	Descrição
text (padrão)	JSON com conteúdo em texto simples, posição do cursor e dimensões
ansi	JSON com códigos de escape ANSI preservados no campo de conteúdo
png	Captura de tela colorida como imagem PNG (requer @resvg/resvg-js)

{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

O formato ansi reconstrói sequências de escape SGR do buffer de células do terminal, preservando atributos de 16 cores, 256 cores e truecolor de 24 bits, juntamente com estilos negrito, esmaecido, itálico e sublinhado.

O formato png retorna um bloco de conteúdo MCP image com dados PNG codificados em base64, renderizado com o tema de cores One Dark e moldura de janela estilo macOS.

startRecording

Inicia a gravação da saída do terminal em um arquivo asciicast v2.

{
  "name": "startRecording",
  "arguments": {
    "mode": "always",
    "idleTimeLimit": 2,
    "maxDuration": 3600
  }
}

Opções:

• mode: always (salvar tudo) ou on-failure (salvar apenas em saída com código diferente de zero)
• outputDir: Diretório de saída personalizado
• idleTimeLimit: Máximo de segundos entre eventos (limita pausas na reprodução)
• maxDuration: Parada automática após N segundos
• inactivityTimeout: Parada automática após N segundos sem saída

stopRecording

Interrompe uma gravação e finaliza o arquivo asciicast.

{
  "name": "stopRecording",
  "arguments": {
    "recordingId": "abc123"
  }
}

createSession

Cria uma nova sessão de terminal e retorna seus metadados. Use o sessionId retornado para direcionar esta sessão em chamadas de ferramenta subsequentes.

{
  "name": "createSession",
  "arguments": {
    "shell": "/bin/zsh",
    "cols": 100,
    "rows": 30
  }
}

Todos os argumentos são opcionais. Retorna:

{
  "sessionId": "3029d",
  "shell": "/bin/zsh",
  "cols": 100,
  "rows": 30,
  "createdAt": "2026-04-25T12:58:01.072Z",
  "lastActivityAt": "2026-04-25T12:58:01.072Z",
  "isDefault": false
}

listSessions

Lista todas as sessões ativas, incluindo a padrão. Informa os limites configurados.

{ "name": "listSessions", "arguments": {} }

destroySession

Destrói uma sessão por ID. A sessão padrão não pode ser destruída.

{
  "name": "destroySession",
  "arguments": { "sessionId": "3029d" }
}

Multi-Sessão

Por padrão, toda chamada de ferramenta sem um sessionId direciona uma única sessão padrão criada automaticamente — o mesmo comportamento que o projeto sempre teve. Passe sessionId para operar múltiplos PTYs isolados a partir de um único processo.

• A sessão padrão é criada no primeiro uso e não pode ser destruída.
• Sessões adicionais são criadas por createSession e rastreadas até serem destruídas ou removidas por inatividade (--session-idle-timeout, padrão 600s).
• Sessões simultâneas são limitadas a --max-sessions (padrão 5).
• Uma gravação ativa captura a saída de todas as sessões no processo.

Caso de uso típico: um agente de IA operando uma compilação de longa duração em uma sessão enquanto executa diagnósticos em outra, sem intercalação de comandos.

Modo Sandbox

Execute o terminal com acesso restrito a arquivos e rede:

# Interactive permission configuration
terminal-mcp --sandbox

# With a config file
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json

O modo interativo mostra um diálogo TUI para configurar permissões:

- **Leitura/Escrita**: Acesso total (diretório atual, /tmp, caches) - **Somente Leitura**: Pode ler, mas não modificar (diretório home) - **Bloqueado**: Sem acesso (chaves SSH, credenciais de nuvem, tokens de autenticação)

Exemplo de arquivo de configuração:

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

Suporte de plataforma:

• macOS: Suporte completo via sandbox-exec (Seatbelt)
• Linux: Suporte completo via bubblewrap (requer bwrap instalado)
• Windows: Fallback gracioso (executa sem sandbox)

Consulte a Documentação do Sandbox para opções de configuração detalhadas.

Gravação

O Terminal MCP pode gravar sessões no formato asciicast v2, compatível com asciinema para reprodução.

Início Rápido

# Start with recording enabled
terminal-mcp --record

# Run your commands, then exit
exit

# Output shows the saved file path:
# Recordings saved:
#   ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
#
# Play with: asciinema play <file>

Reprodução

Instale o asciinema para reproduzir gravações:

# macOS
brew install asciinema

# Linux/pip
pip install asciinema

# Play a recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

# Play at 2x speed
asciinema play -s 2 recording.cast

Modos de Gravação

• always (padrão): Salvar todas as gravações
• on-failure: Salvar apenas se a sessão sair com código diferente de zero (útil para depurar execuções de CI com falha)

# Only save recordings when something fails
terminal-mcp --record=on-failure

Gravação via Ferramenta MCP

Assistentes de IA também podem controlar a gravação programaticamente via ferramentas MCP:

1. Chame startRecording para começar a capturar
2. Execute operações no terminal
3. Chame stopRecording para finalizar e salvar

Isso permite fluxos de trabalho orientados por IA, como "grave esta sessão de depuração" ou "capture esta demonstração".

Arquitetura

O Terminal MCP tem três modos de operação:

Modo	Flag	Stdin	Descrição
Interativo	(padrão)	TTY	O usuário obtém um shell; a IA se conecta via socket Unix
Cliente	(padrão)	não-TTY	Conecta-se ao socket de uma sessão interativa, serve MCP via stdio
Headless	--headless	qualquer	Autônomo: PTY embutido + servidor MCP via stdio

Modo headless (recomendado para configurações MCP)

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP SDK (@modelcontextprotocol/sdk)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

Modo interativo + cliente (dois processos)

terminal-mcp (interactive, in your terminal)
    ├── User shell (stdin/stdout)
    └── Unix socket server (/tmp/terminal-mcp.sock)
            ▲
            │ JSON-RPC over socket
            ▼
terminal-mcp (client, spawned by MCP client)
    └── MCP server (stdio transport)

Exemplo de Sessão

# Type a command
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}

# Send Enter key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}

# Get the output
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}

Desenvolvimento

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (development)

Documentação

Consulte a pasta docs para documentação detalhada:

• Visão Geral
• Instalação
• Referência de Ferramentas
• Gravação
• Configuração
• Modo Sandbox
• Exemplos
• Arquitetura

Requisitos

• Node.js 18.0.0 ou posterior
• Windows 10 versão 1809 ou posterior (para suporte a ConPTY)

Licença

MIT