WSL Exec

Execute comandos de forma segura no Subsistema Windows para Linux (WSL).

GitHub
20
Experimente este MCPPatrocinado

Documentação

mcp-wsl-exec

Um servidor Model Context Protocol (MCP) para usuários de Windows + Claude Desktop interagirem com o Windows Subsystem for Linux (WSL). Oferece capacidades de coleta de informações somente leitura e execução segura de comandos.

⚠️ Importante: Quem Deve Usar Isto?

✅ Você DEVE usar isto se:

  • Você está usando Claude Desktop no Windows
  • Você precisa interagir com seu ambiente WSL
  • Você quer fornecer contexto WSL ao Claude (informações do sistema, processos, arquivos, etc.)

❌ Você NÃO precisa disto se:

  • Você está usando Claude Code (ele tem acesso nativo ao bash)
  • Você está em Linux/macOS (use ferramentas nativas em vez disso)
  • Você só precisa de Windows PowerShell/CMD (use um servidor MCP diferente)

Recursos

📊 Coleta de Informações (Somente Leitura)

  • 🖥️ Obter informações do sistema (SO, kernel, hostname)
  • 📁 Navegar pelo conteúdo de diretórios
  • 💾 Verificar uso de disco
  • ⚙️ Listar variáveis de ambiente
  • 🔄 Monitorar processos em execução

🔧 Execução de Comandos (Com Segurança)

  • 🔒 Execução segura de comandos em ambientes WSL
  • ⚡ Recursos de segurança integrados:
    • Detecção de comandos perigosos
    • Sistema de confirmação de comandos
    • Prevenção de travessia de caminho
    • Sanitização de comandos
  • 📁 Suporte a diretório de trabalho
  • ⏱️ Funcionalidade de timeout de comando
  • 🛡️ Proteção contra injeção de shell

Configuração

Este servidor requer configuração através do seu cliente MCP. Aqui estão exemplos para diferentes ambientes:

Configuração do Cline

Adicione isto às configurações MCP do Cline:

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

Configuração do Claude Desktop

Adicione isto à configuração do Claude Desktop:

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

API

O servidor fornece 7 ferramentas MCP:

Coleta de Informações (Somente Leitura) 📊

Estas ferramentas fornecem contexto sobre seu ambiente WSL sem fazer alterações:

get_system_info

Obter informações do sistema (versão do SO, kernel, hostname).

Parâmetros: Nenhum

get_directory_info

Obter conteúdo de diretório e informações de arquivos.

Parâmetros:

  • path (string, opcional): Caminho do diretório (padrão é o diretório atual)
  • details (boolean, opcional): Mostrar informações detalhadas (permissões, tamanhos, etc.)

get_disk_usage

Obter informações de espaço em disco.

Parâmetros:

  • path (string, opcional): Caminho específico para verificar (padrão é todos os sistemas de arquivos)

get_environment

Obter variáveis de ambiente.

Parâmetros:

  • filter (string, opcional): Padrão de filtro para buscar variáveis específicas

list_processes

Listar processos em execução.

Parâmetros:

  • filter (string, opcional): Filtrar por nome do processo

Execução de Comandos (Potencialmente Destrutiva) 🔧

Use estas ferramentas quando precisar fazer alterações ou executar comandos personalizados:

execute_command

Executar um comando no WSL com verificações de segurança e validação.

Parâmetros:

  • command (string, obrigatório): Comando a ser executado
  • working_dir (string, opcional): Diretório de trabalho para execução do comando
  • timeout (number, opcional): Timeout em milissegundos

Nota: Comandos perigosos exigirão confirmação via confirm_command.

confirm_command

Confirmar a execução de um comando perigoso que foi sinalizado pelas verificações de segurança.

Parâmetros:

  • confirmation_id (string, obrigatório): ID de confirmação recebido de execute_command
  • confirm (boolean, obrigatório): Se deve prosseguir com a execução do comando

Recursos de Segurança

Detecção de Comandos Perigosos

O servidor mantém uma lista de comandos potencialmente perigosos que exigem confirmação explícita antes da execução, incluindo:

  • Operações de sistema de arquivos (rm, rmdir, mv)
  • Comandos do sistema (shutdown, reboot)
  • Gerenciamento de pacotes (apt, yum, dnf)
  • Redirecionamentos de arquivo (>, >>)
  • Alterações de permissão (chmod, chown)
  • E mais...

Validação de Comandos

Os comandos são executados através de bash -c, portanto a sintaxe normal do shell, como pipes, aspas, redirecionamentos e encadeamento de comandos, é preservada. O servidor valida entradas vazias/com byte nulo, cita argumentos usados por ferramentas integradas e exige confirmação para comandos potencialmente perigosos.

Desenvolvimento

Configuração

  1. Clone o repositório
  2. Instale as dependências:
pnpm install
  1. Compile o projeto:
pnpm build
  1. Execute em modo de desenvolvimento:
pnpm dev

Publicação

O projeto usa changesets para gerenciamento de versão. Para publicar:

  1. Crie um changeset:
pnpm changeset
  1. Versione o pacote:
pnpm changeset version
  1. Publique no npm:
pnpm release

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos