cmux-mcp

cmux-mcp

한국어

Servidor MCP que dá aos agentes de IA controle total do seu terminal cmux.

Deixe o Claude executar comandos, ler saídas, gerenciar abas/painéis/workspaces/janelas e enviar caracteres de controle no seu terminal cmux — tudo através do Model Context Protocol. Funciona em segundo plano. Sem roubo de foco.

Início Rápido

Opção A: Plugin Claude Code (Recomendado)

/plugin marketplace add daegweon/cmux-mcp
/plugin install cmux-mcp@cmux-tools

É isso. O servidor MCP é configurado automaticamente.

Opção B: npx (Sem necessidade de build)

Edite ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "npx",
      "args": ["-y", "cmux-mcp"]
    }
  }
}

Reinicie o Claude Code.

Opção C: Clonar e compilar

git clone https://github.com/daegweon/cmux-mcp.git
cd cmux-mcp
npm install && npm run build

Edite ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Reinicie o Claude Code.

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Requisitos

• macOS
• cmux.app instalado e em execução
• Node.js 18+
• Modo de controle do socket cmux definido como Automação ou Acesso Aberto (Configurações > Automação > Modo de Controle do Socket)

Ferramentas

O cmux-mcp expõe toda a CLI do cmux como ferramentas MCP. Todas as ferramentas de E/S do terminal suportam um parâmetro opcional surface para direcionar abas específicas.

E/S do Terminal

Gerenciamento de Superfícies (Abas)

Gerenciamento de Painéis

Gerenciamento de Janelas

Gerenciamento de Workspaces

Pesquisa e Estrutura

Notificações

Metadados da Barra Lateral

Log

Buffer

Controle do Terminal

Hooks e Diversos

Navegador

Exemplos do Mundo Real

Executar testes e analisar falhas:

"Execute a suíte de testes e me diga quais testes estão falhando"

O Claude envia npm test, lê a saída e resume as falhas.

Sessões SSH multi-abas:

"Abra duas novas abas, conecte via SSH ao server-a em uma e ao server-b na outra, depois compare o uso de disco deles"

O Claude cria abas, envia comandos SSH para cada uma, lê a saída de ambas e compara.

Sessão REPL interativa:

"Abra um REPL Python e verifique se o pandas está instalado"

O Claude inicia python3, digita import pandas, lê o resultado e reporta.

Gerenciamento de processos de longa duração:

"Inicie o servidor de desenvolvimento, aguarde até que esteja pronto e depois execute a verificação de saúde"

O Claude envia o comando de início, verifica a saída até que "ready" apareça e então executa o próximo comando.

Por que cmux-mcp?

Operação em segundo plano

O cmux-mcp usa a CLI nativa do cmux (cmux send, cmux read-screen, cmux send-key) que se comunica via socket Unix. Isso significa:

• Funciona enquanto o cmux está em segundo plano
• Sem roubo de foco da janela
• Sem atrasos de ativação via AppleScript
• Confiável mesmo durante a inicialização do aplicativo

CLI vs AppleScript

Este projeto foi bifurcado de ferrislucas/iterm-mcp e completamente reescrito. Veja o porquê:

Detecção inteligente de conclusão

O cmux-mcp não apenas espera cegamente após enviar um comando. Ele monitora a atividade da CPU do TTY para saber quando um comando realmente termina — mesmo para comandos que produzem saída ao longo do tempo. A partir da v1.3.1, o intervalo de polling foi reduzido de 350ms para 150ms e o limite de inatividade de 1000ms para 500ms, tornando o write_to_terminal aproximadamente 2x mais rápido.

Eficiente em tokens

Os agentes leem apenas as linhas de que precisam. Um npm test que produz 500 linhas de saída? O agente primeiro é informado "500 linhas foram geradas" e depois lê apenas as últimas 20 linhas para verificar erros. Sem desperdício de janela de contexto.

Lidando com Problemas Conhecidos do cmux

A arquitetura do cmux-mcp evita vários casos extremos conhecidos do cmux:

Arquitetura

MCP Client (Claude Code, Claude Desktop, etc.)
    |  stdio
cmux-mcp server
    |  child_process
cmux CLI (send / read-screen / send-key / ...)
    |  Unix socket
cmux.app (Ghostty-based terminal)
    |
macOS PTY

Módulos principais:

Desenvolvimento

npm run build          # Compile TypeScript
npm run watch          # Auto-rebuild on changes
npm test               # Run unit tests
npm run e2e            # Run E2E tests (requires running cmux)
npm run inspector      # Open MCP Inspector for interactive debugging

Segurança

• Sem restrições de comando integradas. Os comandos são executados com as permissões do seu shell.
• Monitore a atividade da IA e interrompa se necessário.
• Comece com tarefas focadas até se familiarizar com o comportamento do modelo.

Créditos

• Bifurcado de ferrislucas/iterm-mcp
• Construído para cmux por manaflow.ai

Privacidade

O cmux-mcp não coleta nem transmite nenhum dado. Todo o processamento é local. Consulte PRIVACY.md para detalhes.

Licença

MIT