Local Commander

---

O problema

Sua IA pode escrever o código, mas não consegue ver seu projeto. Você copia arquivos para o chat, cola a saída dos testes de volta e executa cada comando você mesmo. Dar a ela um terminal bruto resolve isso, mas então ela pode tocar em tudo.

O Local Commander fica no meio. Sua IA recebe ferramentas reais para trabalho real na sua máquina, dentro das pastas que você escolher, com comandos que você permite. Você continua trabalhando no chat que já está aberto.

Para que as pessoas usam

Código	Executar testes e builds · Corrigir um bug no repositório real · Revisar um diff antes de enviar
Serviços locais	Iniciar um servidor de desenvolvimento · Verificar se um serviço está ativo · Ler seus logs
Contexto do projeto	Obter status, commits recentes e scripts em uma única pergunta · Pesquisar no código · Editar arquivos no lugar

Experimente perguntar:

"Execute os testes no meu-app e me diga o que falha."
"Inicie o servidor de desenvolvimento e verifique se a porta 3000 responde."
"Mostre o que mudou no repositório desde ontem."

Por que o Local Commander

🔒 Você escolhe o acesso. Sua IA vê apenas as pastas que você escolher. Arquivos secretos como .env e chaves privadas são bloqueados por padrão.

🧰 Ferramentas reais, não um shell bruto. Os comandos são executados a partir de uma lista de permissões (Git, Node, npm, Python e similares) com argumentos separados. Não há string de shell livre para injetar.

⚡ Trabalho paralelo sem colisões. Comandos independentes são executados lado a lado. Processos de longa duração, como servidores de desenvolvimento, continuam rodando enquanto sua IA verifica a saída deles.

🏠 Fica na sua máquina. O servidor roda localmente e fala apenas com o cliente de IA que o iniciou. Sem conta, sem telemetria, e o log de auditoria fica desligado a menos que você o ative.

🔌 Funciona com a IA que você já tem. Claude Desktop, Claude Code, Cursor, Codex, ChatGPT via túnel, ou qualquer coisa que fale MCP.

Comece agora

Escolha a forma que melhor se adapta a você. Cada uma leva alguns minutos.

Você usa	Faça isto
Claude Desktop	Baixe o arquivo .mcpb da última versão e abra-o. Escolha suas pastas. Não precisa de Node.js.
Claude Desktop ou Cursor, com Node.js 20+	npx -y local-commander-mcp-agent setup --root /path/to/your/projects --client all e reinicie o aplicativo.
Claude Code	claude mcp add local-commander -- npx -y local-commander-mcp-agent --stdio /path/to/your/projects
Docker	Monte seus projetos em ghcr.io/netbka/local-commander-mcp-agent. Veja Docker.
Qualquer outro cliente MCP	Execute npx -y local-commander-mcp-agent --stdio /path/to/your/projects. Veja npx.

Antes de instalar

O que minha IA pode tocar?

Apenas as pastas que você escolher, e somente através das ferramentas do Local Commander: leitura e edição de arquivos, inspeção de Git, comandos permitidos, processos de desenvolvimento e requisições para localhost. Você pode alterar a lista de comandos no arquivo de configuração.

É uma sandbox?

Não. As ferramentas de arquivo são limitadas às suas pastas, mas um programa permitido como node ou python roda com as permissões da sua conta e pode ler o que você pode ler. Para isolamento rígido, use a imagem Docker, uma conta separada de baixo privilégio ou uma VM.

Meus dados vão para algum lugar?

Não. O servidor roda no seu computador e fala apenas com o cliente de IA que o iniciou. Não há telemetria. O que seu cliente de IA envia ao provedor dele é entre você e esse provedor.

Posso removê-lo?

Sim. npx -y local-commander-mcp-agent setup --remove remove do Claude Desktop e do Cursor e mantém um backup da configuração anterior. No Claude Desktop, você também pode desativar ou remover a extensão.

E sobre vários computadores ou uma equipe?

Esta edição de código aberto roda em um computador por vez. O serviço hospedado em localcmd.app conecta ChatGPT, Claude ou seu próprio agente a todos os seus PCs com Windows de uma vez, executa tarefas em várias máquinas em paralelo e mostra qual computador executou o quê. É um produto separado e não é necessário para este.

---

Referência técnica

• Ferramentas
• Opções de instalação: setup · npx · Docker · Node.js · HTTP e ChatGPT
• Modelo de segurança
• Configuração
• Desenvolvimento

Ferramentas

Ferramenta	Finalidade
project_snapshot	Contexto do repositório em uma chamada: status, diff stat, commits recentes, scripts do pacote, processos gerenciados
fs_read, fs_list, fs_search	Leituras limitadas, listagens e busca de texto dentro das raízes permitidas
fs_write, fs_replace	Criar/substituir um arquivo, ou uma substituição exata e direcionada
git_status, git_diff, git_log	Inspeção compacta de Git
command_run, parallel_command_run	Um ou vários executáveis permitidos com argumentos separados
process_start, process_list, process_output, process_kill	Processos de desenvolvimento de longa duração
scheduler_status	Trabalho ativo/na fila e bloqueios de recursos
localhost_request	HTTP limitado apenas a hosts locais permitidos

Opções de instalação

Setup em um comando

Requisitos: Node.js 20+.

npx -y local-commander-mcp-agent setup --root /path/to/your/projects --client all

Isso adiciona uma entrada local-commander à configuração MCP do Claude Desktop e/ou Cursor, mantendo um backup com timestamp do arquivo anterior. Repita --root para mais pastas, use --client claude-desktop ou --client cursor para um cliente, --dry-run para pré-visualizar e setup --remove para remover a entrada novamente. Reinicie o cliente depois.

npx

Requisitos: Node.js 20+. As pastas que o servidor pode acessar seguem --stdio:

{
  "mcpServers": {
    "local-commander": {
      "command": "npx",
      "args": ["-y", "local-commander-mcp-agent", "--stdio", "/path/to/your/projects"]
    }
  }
}

No Windows, alguns clientes precisam de "command": "cmd" com "args": ["/c", "npx", "-y", ...]; setup escreve esse formato para você.

LCMCP_ROOTS ainda funciona em vez de argumentos de pasta. No modo stdio, o estado local é mantido em ~/.local-commander-mcp-agent a menos que LCMCP_OAUTH_STATE_PATH esteja definido.

No Windows, use ; entre várias raízes e caminhos como C:\\Users\\you\\source\\repos. O pacote inclui o pequeno auxiliar de leitura de arquivos do Windows, então nada é compilado na instalação.

Docker

O contêiner é a sandbox: o servidor só vê as pastas que você monta em /workspace. A imagem é publicada como ghcr.io/netbka/local-commander-mcp-agent (tags latest e cada versão). Para compilar você mesmo: docker build -t local-commander-mcp-agent .

Configuração do cliente MCP (Claude Desktop, Cursor, Claude Code, Codex e outros):

{
  "mcpServers": {
    "local-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/projects:/workspace/projects",
        "ghcr.io/netbka/local-commander-mcp-agent"
      ]
    }
  }
}

No Windows, use um caminho como C:\\Users\\you\\source\\repos:/workspace/repos. A imagem contém Node.js 22, Git e Python 3. Adicione ferramentas estendendo a imagem.

HTTP em vez de stdio:

docker run --rm -p 127.0.0.1:17321:17321 \
  -e LCMCP_TOKEN=generate-a-long-random-token \
  -v /path/to/your/projects:/workspace/projects \
  ghcr.io/netbka/local-commander-mcp-agent --http

A imagem usa como padrão --stdio; qualquer outro argumento após o nome da imagem (aqui --http) o substitui e inicia o servidor HTTP. O endpoint é http://127.0.0.1:17321/mcp com Authorization: Bearer <token>. Publique a porta apenas em 127.0.0.1.

Node.js

Requisitos: Node.js 20+.

npm install
npm run build

{
  "mcpServers": {
    "local-commander": {
      "command": "node",
      "args": ["/path/to/local-commander-mcp-agent/dist/index.js", "--stdio", "/path/to/your/projects"]
    }
  }
}

No modo stdio, a saída padrão carrega apenas mensagens MCP e os logs vão para o erro padrão. As configurações de autenticação HTTP não se aplicam, porque apenas o cliente que iniciou o processo pode falar com ele.

No Windows, a compilação também gera um pequeno auxiliar de leitura de arquivos (release/personal/OwnerBridge.exe) com o compilador .NET Framework que acompanha o Windows. Outras plataformas usam o leitor Node.

HTTP e ChatGPT

cp local-commander.config.example.json local-commander.config.json   # set "roots"
LCMCP_AUTH_MODE=oauth LCMCP_PUBLIC_BASE_URL=https://your-tunnel.example.com npm start

Quando o cliente inicia a autorização, um código de aprovação de uso único é exibido no terminal local. O modo Bearer (LCMCP_AUTH_MODE=bearer, LCMCP_TOKEN=...) está disponível para clientes locais.

Modelo de segurança

• Operações diretas de arquivo são restritas às raízes configuradas; caminhos existentes são resolvidos com realpath, então symlinks não podem escapar de uma raiz.
• Arquivos secretos comuns (.env, chaves privadas, arquivos de credenciais) são bloqueados por padrão.
• command_run recebe um executável e um array de argumentos, nunca uma string de shell. Executáveis são permitidos e resolvidos apenas a partir de diretórios absolutos PATH.
• O tempo e a saída dos comandos são limitados; HTTP é restrito a localhost e redirecionamentos não são seguidos.
• Processos filhos não são isolados pelo SO fora do Docker: um interpretador permitido pode ler qualquer coisa que a conta possa ler. Para contenção rígida, use a imagem Docker, uma conta separada de baixo privilégio ou uma VM.

Configuração

Variável	Significado
LCMCP_TRANSPORT	stdio para servir via stdio (igual a --stdio)
LCMCP_ROOTS	Raízes permitidas separadas pelo delimitador de caminho do SO (; no Windows, : em outros lugares)
LCMCP_CONFIG	Caminho do arquivo de configuração (padrão local-commander.config.json no diretório de trabalho)
LCMCP_HOST, LCMCP_PORT, LCMCP_MCP_PATH	Bind e caminho HTTP
LCMCP_AUTH_MODE	Somente HTTP: oauth, bearer ou none
LCMCP_TOKEN	Token para o modo bearer
LCMCP_PUBLIC_BASE_URL	Origem HTTPS pública usada como emissor/recurso OAuth
LCMCP_OAUTH_STATE_PATH	Caminho do arquivo de estado OAuth e local
LCMCP_AUDIT_MODE	off (padrão), minimal, diagnostic ou full (completo requer LCMCP_AUDIT_RECOVERY_KEY)

O arquivo de configuração também pode definir a lista de permissões de comandos (shell.allowedCommands), limites de tamanho e hosts localhost; veja local-commander.config.example.json.

Desenvolvimento

npm run typecheck
npm test
npm run build

---