Servidor MCP Tmux | Awesome MCP Servers

Este é um software experimental destinado exclusivamente a fins de teste e desenvolvimento. Não use em ambientes de produção ou com dados sensíveis.

Um servidor Model Context Protocol (MCP) que fornece execução persistente de shell por meio de sessões tmux. Este servidor permite que assistentes de IA executem comandos em um shell persistente. Isso desbloqueia muitas possibilidades, como Orquestração de Agentes... final_optimized

Recursos

Arquitetura de Duas Janelas: Cada workspace possui duas janelas - exec para execução de comandos e ui para exibição limpa de saída
Workspaces Persistentes: Execute comandos em sessões tmux que persistem entre reinicializações do cliente MCP
Suporte a Processos Interativos: Lide com processos de longa duração, REPLs e comandos interativos
Isolamento de Workspace: Múltiplos workspaces isolados para diferentes projetos ou tarefas
Gerenciamento de UI Limpo: Janelas separadas para execução e saída voltada ao usuário
Gerenciamento Automático de Sessões: Crie, destrua e monitore workspaces de forma integrada

Instalação

🚨 AVISO DE SEGURANÇA: Este software permite que assistentes de IA executem comandos shell arbitrários no seu sistema. Instale e use apenas em ambientes de teste isolados. Nunca use em sistemas com dados sensíveis ou em ambientes de produção.

Pré-requisitos

Node.js 18.0.0 ou superior
tmux instalado no seu sistema
- Ubuntu/Debian: sudo apt install tmux
- macOS: brew install tmux
- CentOS/RHEL: sudo yum install tmux

Instalar a partir do npm

npm install -g tmux-mcp-server

Instalar a partir do código-fonte

git clone https://github.com/TNTisdial/persistent-shell-mcp.git
cd persistent-shell-mcp
npm install
npm link

Uso

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "tmux-shell": {
      "command": "tmux-mcp-server"
    }
  }
}

Ferramentas Disponíveis

Ferramentas Principais de Execução

`execute_command`

Execute comandos que terminam rapidamente e retornam a saída completa. Usa a janela exec.

execute_command({
  command: "ls -la", 
  workspace_id: "my-project"
})

`start_process`

Inicie processos de longa duração ou interativos. Pode direcionar qualquer janela:

Janela exec (padrão): Para processos em segundo plano
Janela ui: Para aplicações interativas que precisam de visibilidade do usuário

start_process({
  command: "python3", 
  workspace_id: "dev",
  target_window: "ui"  // For interactive apps like vim, python REPL
})

`get_output`

Capture a saída atual do terminal de qualquer janela:

Janela ui (padrão): Saída limpa voltada ao usuário
Janela exec: Shell bruto com todos os comandos

get_output({
  workspace_id: "dev",
  window_name: "ui"  // or "exec" for raw output
})

`send_input`

Envie entrada para processos em execução em qualquer janela.

send_input({
  text: "print('Hello World')", 
  workspace_id: "dev",
  target_window: "ui"
})

`stop_process`

Pare o processo atualmente em execução na janela de execução (envia Ctrl+C).

stop_process({workspace_id: "dev"})

Ferramentas de Gerenciamento de Workspace

`create_workspace`

Crie um novo workspace isolado com janelas duplas.

`destroy_workspace`

Destrua um workspace e todos os seus processos.

`list_workspaces`

Liste todos os workspaces ativos.

Arquitetura

Design de Duas Janelas

Cada workspace consiste em duas janelas tmux:

Janela exec: Shell bruto para execução de comandos
- Lida com toda a execução de comandos
- Mostra histórico completo do shell e prompts
- Usada para processos em segundo plano
Janela ui: Exibição limpa de saída
- Mostra saída limpa para interação do usuário
- Usada para aplicações interativas
- Proporciona melhor experiência ao usuário

Isolamento de Workspace

Cada workspace é uma sessão tmux separada
Diretórios de trabalho e ambientes independentes
Processos não interferem entre workspaces
Separação limpa de diferentes projetos/tarefas

Fluxos de Trabalho Comuns

Execução Rápida de Comandos

// Execute and get results immediately
execute_command({command: "npm install", workspace_id: "frontend"})
execute_command({command: "git status", workspace_id: "frontend"})

Desenvolvimento Interativo

// Start Python REPL in UI window
start_process({
  command: "python3", 
  workspace_id: "python-dev",
  target_window: "ui"
})

// Send Python commands
send_input({text: "import os", workspace_id: "python-dev", target_window: "ui"})
send_input({text: "print(os.getcwd())", workspace_id: "python-dev", target_window: "ui"})

// Check output
get_output({workspace_id: "python-dev", window_name: "ui"})

Gerenciamento de Processos em Segundo Plano

// Start server in background
start_process({command: "npm run dev", workspace_id: "server"})

// Check server status
get_output({workspace_id: "server", window_name: "exec"})

// Stop server when done
stop_process({workspace_id: "server"})

Desenvolvimento Multi-Projeto

// Frontend workspace
create_workspace({workspace_id: "frontend"})
execute_command({command: "cd /path/to/frontend", workspace_id: "frontend"})

// Backend workspace  
create_workspace({workspace_id: "backend"})
execute_command({command: "cd /path/to/backend", workspace_id: "backend"})

// Database workspace
create_workspace({workspace_id: "database"})
start_process({command: "mysql -u root -p", workspace_id: "database", target_window: "ui"})

Estrutura do Projeto

tmux-mcp/
├── src/
│   ├── server.js          # Main MCP server and tool definitions
│   ├── tmux-manager.js    # Tmux session and window management
│   └── index.js           # Entry point
├── bin/
│   └── tmux-mcp-server    # Executable script
├── package.json
└── README.md

Solução de Problemas

Tmux Não Encontrado

Error: tmux command not found

Instale o tmux: sudo apt install tmux (Ubuntu/Debian) ou brew install tmux (macOS)

Falha na Criação do Workspace

Error: Failed to create workspace

Verifique se o servidor tmux está em execução e se você tem permissões para criar sessões

Comandos Não Respondendo

Check workspace status with get_output

Use get_output com window_name: "exec" para ver o estado bruto do shell

Processo Travado

Use stop_process to send Ctrl+C

Envie sinal de interrupção com stop_process para encerrar processos pendurados

Licença

MIT

Tmux MCP Server

Documentação