Documentação

WSL + Windows Workspace Connector

Conector MCP local que dá ao Claude acesso controlado à sua máquina: terminal do WSL, PowerShell do Windows, sessões persistentes e arquivos dentro das pastas que você libera.

O que ele faz

Executa comandos no WSL (bash) e no Windows (PowerShell), avulsos ou em sessões que guardam a pasta atual.
Lê, escreve e lista arquivos, sempre dentro das pastas liberadas.
Abre arquivos, pastas e URLs no Windows com o app padrão.
Detecta sozinho a distro WSL, o usuário Linux e o usuário Windows. Por padrão libera /home/<usuário-linux> e /mnt/c/Users/<usuário-windows>.
No Claude Code, que já tem terminal próprio, entra em modo silencioso e não gasta contexto.

Instalar

Requisitos

Windows 10 ou 11 com WSL 2 (ou Linux/WSL, sem as ferramentas de Windows).
Node.js 20 ou mais novo.

Como plugin do Claude (Cowork e Claude Code)

Instale o plugin conector-wsl pelo diretório de plugins do Claude. O plugin sobe o servidor com node ${CLAUDE_PLUGIN_ROOT}/src/index.js, e o Claude instala as dependências (@modelcontextprotocol/sdk e zod) a partir do package-lock.json.

Pelo npm

npm install -g claude-wsl-terminal-connector

O instalador adiciona o conector ao Claude Desktop. Depois, reinicie o Claude Desktop.

Pelo arquivo .mcpb

Baixe o .mcpb do release mais recente e abra no Claude Desktop em Settings › Extensions › Install from file.

Ferramentas

Ferramenta	O que faz	Tipo
`connector_status`	Modo, distro, pastas liberadas e se o PowerShell está disponível.	leitura
`list_allowed_roots`	Lista as pastas liberadas.	leitura
`list_directory`	Lista arquivos e pastas.	leitura
`get_path_info`	Tipo, tamanho e datas de um caminho.	leitura
`read_text_file`	Lê um arquivo de texto (UTF-8).	leitura
`write_text_file`	Cria ou sobrescreve um arquivo de texto.	destrutiva
`create_directory`	Cria uma pasta.	escrita
`run_wsl_command`	Executa um comando no WSL em shell nova.	destrutiva
`start_wsl_session`	Abre uma sessão WSL que guarda pasta e variáveis exportadas.	escrita
`run_in_wsl_session`	Executa um comando dentro da sessão.	destrutiva
`close_wsl_session`	Fecha a sessão.	escrita
`run_windows_command`	Executa PowerShell no Windows em shell nova.	destrutiva
`start_windows_session`	Abre uma sessão PowerShell que guarda a pasta atual.	escrita
`run_in_windows_session`	Executa um comando dentro da sessão PowerShell.	destrutiva
`close_windows_session`	Fecha a sessão PowerShell.	escrita
`open_in_windows`	Abre arquivo, pasta ou URL no Windows.	escrita

As ferramentas de Windows só aparecem quando o PowerShell é encontrado (Windows nativo ou WSL com interop).

Exemplos de uso

“Rode npm test no projeto ~/myprojects/app e me diga o que falhou.”
“Liste os arquivos da minha Área de Trabalho no Windows.”
“Abra uma sessão no WSL, entre em ~/site e faça o build.”
“Abra o relatório C:\Users\eu\Documents\relatorio.pdf.”

Configurar (opcional)

Tudo é detectado sozinho. Se quiser mudar, use estes campos (ou as variáveis de ambiente):

Campo	Variável	Padrão
Diretório inicial	`WSL_CONNECTOR_DEFAULT_CWD`	`/home/<usuário>`
Pastas liberadas	`WSL_CONNECTOR_ALLOWED_ROOTS`	home do WSL e pasta do usuário no Windows
Distro WSL	`WSL_CONNECTOR_DISTRO`	a distro padrão
Tempo limite	`WSL_CONNECTOR_TIMEOUT_MS`	120000 ms
Modo	`WSL_CONNECTOR_MODE`	`auto` (full no Windows, silent no Claude Code em Linux)

Segurança e o que ele executa

Toda operação de arquivo e de terminal é validada contra as pastas liberadas. Caminhos fora delas são recusados.
Os comandos rodam com o seu usuário, com as mesmas permissões que você tem no terminal.
Processos iniciados: wsl.exe --exec bash -lc (ou /bin/bash -lc no Linux) e powershell.exe.
Nenhuma requisição de rede. A única exceção é opcional: com WSL_CONNECTOR_PREWARM definido, ele roda npx -y <pacote@versão> --help para aquecer o cache do npm. O plugin não define essa variável.
Sem telemetria. Veja a política de privacidade.

Limites conhecidos

Não há TTY interativo real (programas que pedem entrada no meio da execução não funcionam).
Sessões WSL guardam a pasta e as variáveis exportadas; aliases e funções não persistem.
Sessões PowerShell guardam só a pasta atual.
Arquivos são tratados como texto UTF-8.

Suporte

Dúvidas, bugs e sugestões: abra uma issue no GitHub. Código-fonte em github.com/denerbatista/conector-wsl.