Terminal MCP Server

Execute comandos em hosts locais ou remotos via SSH. Suporta persistência de sessão e variáveis de ambiente.

Documentação

Terminal MCP Server

Aviso

O projeto atual não está mais em manutenção. Recomendo que vocês usem uma ferramenta de comando mais avançada —— Desktop Commander
O projeto atual não está mais em manutenção. Recomendo a todos que usem a ferramenta MCP de terminal mais avançada Desktop Commander

Documentação em chinês

O Terminal MCP Server é um servidor do Model Context Protocol (MCP) que permite executar comandos em hosts locais ou remotos. Ele fornece uma interface simples, porém poderosa, para modelos de IA e outras aplicações executarem comandos do sistema, seja na máquina local ou em hosts remotos via SSH.

Recursos

Execução de comandos local: Execute comandos diretamente na máquina local
Execução de comandos remota: Execute comandos em hosts remotos via SSH
Persistência de sessão: Suporte a sessões persistentes que reutilizam o mesmo ambiente de terminal por um tempo especificado (padrão de 20 minutos)
Variáveis de ambiente: Defina variáveis de ambiente personalizadas para comandos
Múltiplos métodos de conexão: Conecte-se via stdio ou SSE (Server-Sent Events)

Instalação

Instalando via Smithery

Para instalar o terminal-mcp-server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @weidwonder/terminal-mcp-server --client claude

Instalação manual

# Clone the repository
git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Uso

Iniciando o servidor

# Start the server using stdio (default mode)
npm start

# Or run the built file directly
node build/index.js

Iniciando o servidor no modo SSE

O modo SSE (Server-Sent Events) permite conectar-se ao servidor remotamente via HTTP.

# Start the server in SSE mode
npm run start:sse

# Or run the built file directly with SSE flag
node build/index.js --sse

Você pode personalizar o servidor SSE com as seguintes opções de linha de comando:

Opção	Descrição	Padrão
`--port` ou `-p`	A porta para escutar	8080
`--endpoint` ou `-e`	O caminho do endpoint	/sse
`--host` ou `-h`	O host ao qual vincular	localhost

Exemplo com opções personalizadas:

# Start SSE server on port 3000, endpoint /mcp, and bind to all interfaces
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

Isso iniciará o servidor e escutará conexões SSE em http://0.0.0.0:3000/mcp.

Testando com o MCP Inspector

# Start the MCP Inspector tool
npm run inspector

A ferramenta execute_command

A ferramenta execute_command é a funcionalidade principal fornecida pelo Terminal MCP Server, usada para executar comandos em hosts locais ou remotos.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
command	string	Sim	O comando a ser executado
host	string	Não	O host remoto ao qual conectar. Se não for fornecido, o comando será executado localmente
username	string	Obrigatório quando o host é especificado	O nome de usuário para conexão SSH
session	string	Não	Nome da sessão, padrão é "default". O mesmo nome de sessão reutilizará o mesmo ambiente de terminal por 20 minutos
env	object	Não	Variáveis de ambiente, padrão é um objeto vazio

Exemplos

Executando um comando localmente

{
  "command": "ls -la",
  "session": "my-local-session",
  "env": {
    "NODE_ENV": "development"
  }
}

Executando um comando em um host remoto

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "session": "my-remote-session",
  "env": {
    "NODE_ENV": "production"
  }
}

Configurando com assistentes de IA

Configurando com Roo Code

Abra o VSCode e instale a extensão Roo Code
Abra o arquivo de configurações do Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
Adicione a seguinte configuração:

Para o modo stdio (conexão local)

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

Para o modo SSE (conexão remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Substitua localhost:8080/sse pelo endereço do servidor, porta e endpoint reais se você os personalizou.

Configurando com Cline

Abra o arquivo de configurações do Cline: ~/.cline/config.json
Adicione a seguinte configuração:

Para o modo stdio (conexão local)

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

Para o modo SSE (conexão remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Configurando com Claude Desktop

Abra o arquivo de configurações do Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Adicione a seguinte configuração:

Para o modo stdio (conexão local)

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

Para o modo SSE (conexão remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Melhores práticas

Execução de comandos

Antes de executar comandos, é melhor determinar o tipo de sistema (Mac, Linux, etc.)
Use caminhos completos para evitar problemas relacionados a caminhos
Para sequências de comandos que precisam manter o ambiente, use && para conectar vários comandos
Para comandos de longa duração, considere usar nohup ou screen/tmux

Conexão SSH

Garanta que a autenticação por chave SSH esteja configurada
Se a conexão falhar, verifique se o arquivo de chave existe (caminho padrão: ~/.ssh/id_rsa)
Certifique-se de que o serviço SSH esteja em execução no host remoto

Gerenciamento de sessão

Use o parâmetro de sessão para manter o ambiente entre comandos relacionados
Para operações que exigem ambientes específicos, use o mesmo nome de sessão
Observe que as sessões serão fechadas automaticamente após 20 minutos de inatividade

Tratamento de erros

Os resultados da execução de comandos incluem tanto stdout quanto stderr
Verifique o stderr para determinar se o comando foi executado com sucesso
Para operações complexas, adicione etapas de verificação para garantir o sucesso

Notas importantes

Para execução remota de comandos, a autenticação por chave SSH deve ser configurada com antecedência
Para execução local de comandos, os comandos serão executados no contexto do usuário que iniciou o servidor
O tempo limite da sessão é de 20 minutos, após o qual a conexão será fechada automaticamente