Desktop Commander MCP

Desktop Commander MCP

Pesquise, atualize, gerencie arquivos e execute comandos de terminal com IA

Trabalhe com código e texto, execute processos e automatize tarefas, indo muito além de outros editores de IA — enquanto usa assinaturas do cliente host em vez de custos com tokens de API.

🖥️ Experimente o Aplicativo Desktop Commander (Beta)

Quer uma experiência melhor? O Aplicativo Desktop Commander oferece tudo o que o servidor MCP faz, além de:

• Use qualquer modelo de IA — Claude, GPT-4.5, Gemini 2.5 ou qualquer modelo que preferir
• Veja alterações de arquivos ao vivo — pré-visualizações visuais de arquivos enquanto a IA edita seus arquivos
• Adicione MCPs e contexto personalizados — estenda com suas próprias ferramentas, sem arquivos de configuração
• Em breve — sistema de habilidades, ditado, tarefas agendadas em segundo plano e muito mais

👉 Baixe o Aplicativo (macOS e Windows)

O servidor MCP abaixo ainda funciona muito bem com o Claude Desktop e outros clientes MCP — o aplicativo é para quem deseja uma experiência dedicada e refinada.

Sumário

• Recursos
• Como instalar
• Primeiros Passos
• Uso
• Interface de Pré-visualização de Arquivos e Editor Markdown
• Lidando com Comandos de Longa Duração
• Trabalho em Andamento e TODOs
• Patrocinadores e Apoiadores
• Site
• Mídia
• Depoimentos
• Perguntas Frequentes
• Contribuindo
• Licença

Todas as suas ferramentas de desenvolvimento de IA em um só lugar. O Desktop Commander coloca todas as ferramentas de desenvolvimento em um único chat. Execute comandos de terminal de longa duração no seu computador e gerencie processos através do Model Context Protocol (MCP). Construído sobre o MCP Filesystem Server para fornecer recursos adicionais de edição de arquivos com busca e substituição.

Recursos

• Controle Remoto por IA - Use o Desktop Commander a partir do ChatGPT, Claude web e outros serviços de IA via Remote MCP
• Interface de Pré-visualização de Arquivos - Pré-visualizações visuais de arquivos no Claude Desktop com markdown renderizado, imagens inline, conteúdo expansível, editor markdown integrado e acesso rápido "Abrir na pasta"
• Comandos de terminal aprimorados com controle interativo de processos
• Execute código em memória (Python, Node.js, R) sem salvar arquivos
• Análise instantânea de dados - basta pedir para analisar arquivos CSV/JSON/Excel
• Suporte nativo a arquivos Excel - Leia, escreva, edite e pesquise arquivos Excel (.xlsx, .xls, .xlsm) sem ferramentas externas
• Suporte a PDF - Leia PDFs com extração de texto, crie novos PDFs a partir de markdown, modifique PDFs existentes
• Suporte a DOCX - Leia, crie, edite e pesquise documentos do Word (.docx) com edição cirúrgica de XML e conversão de markdown para DOCX
• Interaja com processos em execução (SSH, bancos de dados, servidores de desenvolvimento)
• Execute comandos de terminal com streaming de saída
• Suporte a timeout de comandos e execução em segundo plano
• Gerenciamento de processos (listar e encerrar processos)
• Gerenciamento de sessões para comandos de longa duração
• Paginação de saída de processos - Leia a saída do terminal com controles de deslocamento/comprimento para evitar sobrecarga de contexto
• Gerenciamento de configuração do servidor:
  • Obter/definir valores de configuração
  • Atualizar várias configurações de uma vez
  • Alterações dinâmicas de configuração sem reiniciar o servidor
• Operações completas de sistema de arquivos:
  • Ler/escrever arquivos (texto, Excel, PDF, DOCX)
  • Criar/listar diretórios
  • Listagem recursiva de diretórios com profundidade configurável e proteção contra sobrecarga de contexto para pastas grandes
  • Mover arquivos/diretórios
  • Pesquisar arquivos e conteúdo (incluindo conteúdo do Excel)
  • Obter metadados de arquivos
  • Leitura de arquivos com deslocamento negativo: Leia do final dos arquivos usando valores de deslocamento negativos (como o Unix tail)
• Recursos de edição de código:
  • Substituições de texto cirúrgicas para pequenas alterações
  • Reescrita completa de arquivos para alterações maiores
  • Suporte a múltiplos arquivos
  • Substituições baseadas em padrões
  • Pesquisa recursiva de código ou texto em pastas baseada em vscode-ripgrep
• Histórico local de chamadas de ferramentas e logs de auditoria:
  • Chamadas de ferramentas e argumentos são registrados localmente na máquina que executa o Desktop Commander
  • Histórico recente de chamadas com pré-visualizações limitadas de saída disponível através de get_recent_tool_calls
  • Rotação/limpeza baseada em tamanho mantém os arquivos de histórico ativos limitados
• Salvaguardas de segurança (não é uma sandbox — veja SECURITY.md):
  • Prevenção de travessia de symlink em operações de arquivos
  • Lista de bloqueio de comandos para execução acidental
  • Isolamento Docker para isolamento completo

Como instalar

Instalar no Claude Desktop

O Desktop Commander oferece múltiplos métodos de instalação para o Claude Desktop.

📋 Informações de Atualização e Desinstalação: As Opções 1, 2, 3, 4 e 6 têm atualizações automáticas. A Opção 5 requer atualizações manuais. Veja abaixo para detalhes.

npx @wonderwhy-er/desktop-commander@latest setup

npx @wonderwhy-er/desktop-commander@latest setup --debug

curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}

git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Desktop:/mnt/desktop",
        "-v", "/Users/username/Documents:/mnt/documents",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root", 
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/username/Projects:/mnt/Projects",
        "-v", "/Users/username/Downloads:/mnt/Downloads",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

Instalar em Outros Clientes

O Desktop Commander funciona com qualquer cliente compatível com MCP. A configuração JSON padrão é:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

Adicione isso ao arquivo de configuração MCP do seu cliente nos locais abaixo:

claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

Atualizando e Desinstalando o Desktop Commander

Atualizações Automáticas (Opções 1, 2, 3, 4 e 6)

Opção 1 (npx), Opção 2 (instalador bash), 3 (Smithery), 4 (configuração manual) e 6 (Docker) atualizam automaticamente para a versão mais recente sempre que você reiniciar o Claude. Nenhuma intervenção manual é necessária.

Atualizações Manuais (Opção 5)

• Opção 5 (checkout local): cd DesktopCommanderMCP && git pull && npm run setup

Desinstalando o Desktop Commander

🤖 Desinstalação Automática (Recomendada)

A maneira mais fácil de remover completamente o Desktop Commander:

npx @wonderwhy-er/desktop-commander@latest remove

Este desinstalador automático irá:

• ✅ Remover o Desktop Commander da configuração do servidor MCP do Claude
• ✅ Criar um backup da sua configuração do Claude antes de fazer alterações
• ✅ Fornecer orientação para a remoção completa do pacote
• ✅ Restaurar a partir do backup se algo der errado

🔧 Desinstalação Manual

Se o desinstalador automático não funcionar ou se você preferir a remoção manual:

Remover da Configuração do Claude

1. Localize o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Edite o arquivo de configuração:

• Abra o arquivo em um editor de texto
• Encontre e remova a entrada "desktop-commander" da seção "mcpServers"
• Salve o arquivo

Exemplo — Remova esta seção:

{
    "desktop-commander": {
      "command": "npx",
      "args": ["@wonderwhy-er/desktop-commander@latest"]
    }
}

Feche e reinicie o Claude Desktop para concluir a remoção.

🆘 Solução de Problemas

Se a desinstalação automática falhar:

• Use a desinstalação manual como alternativa

Se o Claude não iniciar após a desinstalação:

• Restaure o arquivo de configuração de backup criado pelo desinstalador
• Ou corrija manualmente a sintaxe JSON no seu claude_desktop_config.json

Precisa de ajuda?

• Junte-se à nossa comunidade no Discord: https://discord.com/invite/kQ27sNnZr7

Primeiros Passos

Depois que o Desktop Commander estiver instalado e o Claude Desktop for reiniciado, você estará pronto para turbinar sua experiência com o Claude!

🚀 Integração de Novos Usuários

O Desktop Commander inclui integração inteligente para ajudar você a descobrir o que é possível:

Para novos usuários: Quando você está começando (menos de 10 comandos bem-sucedidos), o Claude oferecerá automaticamente orientações úteis de início e tutoriais práticos depois que você usar o Desktop Commander com sucesso.

Solicite Ajuda a Qualquer Momento: Você pode pedir assistência de integração a qualquer momento simplesmente dizendo:

• "Ajude-me a começar com o Desktop Commander"
• "Mostre-me exemplos do Desktop Commander"
• "O que posso fazer com o Desktop Commander?"

O Claude então mostrará tutoriais e exemplos para iniciantes, incluindo:

• 📁 Organizando sua pasta Downloads automaticamente
• 📊 Analisando arquivos CSV/Excel com Python
• ⚙️ Configurando GitHub Actions CI/CD
• 🔍 Explorando e entendendo bases de código
• 🤖 Executando ambientes de desenvolvimento interativos

Uso

O servidor fornece um conjunto abrangente de ferramentas organizadas em várias categorias:

Ferramentas Disponíveis

Exemplos Rápidos

Análise de Dados:

"Analyze sales.csv and show top customers" → Claude runs Python code in memory

Acesso Remoto:

"SSH to my server and check disk space" → Claude maintains SSH session

Desenvolvimento:

"Start Node.js and test this API" → Claude runs interactive Node session

Exemplos de Uso de Ferramentas

Formato de Bloco de Busca/Substituição:

filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE

Exemplo:

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

Recursos Aprimorados do Bloco de Edição

A ferramenta edit_block inclui várias melhorias para maior confiabilidade:

1. Solicitação Aprimorada: As descrições das ferramentas agora enfatizam fazer múltiplas edições pequenas e focadas em vez de uma grande alteração
2. Busca Difusa de Fallback: Quando correspondências exatas falham, ela executa busca difusa e fornece feedback detalhado
3. Diffs em Nível de Caractere: Mostra exatamente o que é diferente usando o formato {-removed-}{+added+}
4. Suporte a Múltiplas Ocorrências: Pode substituir múltiplas instâncias com o parâmetro expected_replacements
5. Registro Abrangente: Todas as buscas difusas são registradas para análise e depuração

Quando uma busca falha, você verá informações detalhadas sobre a correspondência mais próxima encontrada, incluindo porcentagem de similaridade, tempo de execução e diferenças de caracteres. Todos esses detalhes são registrados automaticamente para análise posterior usando as ferramentas de registro de busca difusa.

Suporte a Docker

🐳 Uso em Ambiente Isolado

O Desktop Commander pode ser executado em contêineres Docker para isolamento completo do seu sistema host, proporcionando risco zero para o seu computador. Isso é perfeito para testes, desenvolvimento ou quando você quer sandboxing completo.

Instruções de Instalação

1. Instale o Docker para Windows/Mac

   • Baixe e instale o Docker Desktop em docker.com

2. Obtenha a Configuração Docker do Desktop Commander

   • Visite: https://hub.docker.com/mcp/server/desktop-commander/manual
   • Opção A: Use o comando de terminal fornecido para configuração automatizada
   • Opção B: Clique em "Standalone" para obter o JSON de configuração e adicione-o manualmente à sua configuração do Claude Desktop

3. Monte Suas Pastas da Máquina (Em Breve)

   • Instruções sobre como montar seus diretórios locais no contêiner Docker serão fornecidas em breve
   • Isso permitirá que você trabalhe com seus arquivos mantendo isolamento completo

Benefícios do Uso de Docker

• Isolamento completo do seu sistema host
• Ambiente consistente em diferentes máquinas
• Limpeza fácil — basta remover o contêiner quando terminar
• Perfeito para testar novos recursos ou configurações

Suporte a URL

• read_file agora pode buscar conteúdo tanto de arquivos locais quanto de URLs
• Exemplo: read_file com o parâmetro isUrl: true para ler de recursos web
• Lida com conteúdo de texto e imagem de fontes remotas
• Imagens (locais ou de URLs) são exibidas visualmente na interface do Claude, não como texto
• O Claude pode ver e analisar o conteúdo real da imagem
• Tempo limite padrão de 30 segundos para solicitações de URL

Visualização de Arquivos e Editor Markdown

O Desktop Commander inclui um widget rico de visualização de arquivos no Claude Desktop que renderiza arquivos visualmente enquanto a IA trabalha com eles.

Tipos de arquivo suportados

• Markdown — visualização renderizada com editor integrado
• Imagens — exibição inline (PNG, JPEG, GIF, WebP, etc.)
• Arquivos de código — visualização de código-fonte com realce de sintaxe
• HTML — visualização renderizada com alternância para visualização de código-fonte
• Diretórios — árvore interativa com expandir/recolher e carregamento preguiçoso
• PDF, Excel, DOCX — extração e exibição nativa de conteúdo

Editor Markdown

Ao visualizar um arquivo .md no Claude Desktop, você pode editá-lo diretamente no painel de visualização — sem necessidade de abrir um aplicativo separado.

Como usar:

1. Peça ao Claude para ler ou criar um arquivo markdown
2. Expanda a visualização do arquivo para tela cheia usando o botão ⤢ Expandir
3. O editor ativa automaticamente no modo tela cheia
4. Edite seu conteúdo com alternância de visualização ao vivo, copiar, desfazer e controles de salvar
5. As alterações são salvas de volta no disco; recolha para retornar à visualização inline Recursos do editor:

• Alternância ao vivo entre editar/visualizar — alterne entre markdown bruto e saída renderizada
• Salvamento automático em disco com indicador de status de salvamento
• Desfazer para reverter alterações não salvas
• Botão Copiar para capturar o código-fonte markdown completo
• Abrir no editor — inicie seu aplicativo markdown padrão diretamente do painel
• Consciência de arquivos parciais — carrega e mescla linhas adjacentes quando o arquivo foi apenas parcialmente lido
• Contexto de seleção de texto — selecione texto no modo de visualização e a IA pode referenciar sua seleção

Navegador de Diretórios

Quando o Claude executa list_directory, o resultado abre como uma árvore de arquivos interativa dentro do painel de visualização — não apenas saída de texto bruto.

Recursos:

• Árvore expansível — pastas expandem e recolhem ao clicar; o conteúdo de nível superior é mostrado imediatamente
• Carregamento preguiçoso — subpastas carregam sob demanda para manter a visualização inicial rápida
• Manipulação de diretórios grandes — diretórios com muitos itens mostram um botão ⚠ click to load all em vez de sobrecarregar a visualização
• Abrir no Finder/Explorer — cada pasta tem um botão de abertura rápida para revelá-la no seu gerenciador de arquivos
• Clique para visualizar — clicar em qualquer arquivo na árvore abre-o diretamente no painel de visualização de arquivos
• Navegação de volta — após abrir um arquivo da árvore, um botão ← Voltar retorna à visualização do diretório

Outros recursos de visualização

• Expandir / recolher — alterne entre linha de resumo compacta e painel completo
• Abrir na pasta — revele o arquivo no Finder/Explorer com um clique
• Carregar mais linhas — carregue incrementalmente conteúdo acima ou abaixo de uma janela de leitura parcial
• Seleção de texto — destaque texto em qualquer visualização; a IA pode ver e referenciar sua seleção

Análise de Logs de Busca Difusa (scripts npm)

O sistema de registro de busca difusa inclui scripts npm convenientes para analisar logs fora do ambiente MCP:

# View recent fuzzy search logs
npm run logs:view -- --count 20

# Analyze patterns and performance
npm run logs:analyze -- --threshold 0.8

# Export logs to CSV or JSON
npm run logs:export -- --format json --output analysis.json

# Clear all logs (with confirmation)
npm run logs:clear

Para documentação detalhada sobre esses scripts, consulte scripts/README.md.

Logs de Busca Difusa

O Desktop Commander inclui registro abrangente para operações de busca difusa na ferramenta edit_block. Quando uma correspondência exata não é encontrada, o sistema realiza uma busca difusa e registra informações detalhadas para análise.

O Que É Registrado

Cada operação de busca difusa registra:

• Texto de busca e texto encontrado: O texto que você está procurando vs. o que foi encontrado
• Pontuação de similaridade: Quão próxima é a correspondência (0-100%)
• Tempo de execução: Quanto tempo a busca levou
• Diferenças de caracteres: Diff detalhado mostrando exatamente o que é diferente
• Metadados do arquivo: Extensão, comprimentos do texto de busca/encontrado
• Códigos de caracteres: Códigos de caracteres específicos que causam diferenças

Localização dos Logs

Os logs são salvos automaticamente em:

• macOS/Linux: ~/.claude-server-commander-logs/fuzzy-search.log
• Windows: %USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log

O Que Você Aprenderá

Os logs de busca difusa ajudam você a entender:

1. Por que correspondências exatas falham: Problemas comuns como diferenças de espaços em branco, finais de linha ou codificação de caracteres
2. Padrões de desempenho: Como a complexidade da busca afeta o tempo de execução
3. Problemas de tipo de arquivo: Quais extensões de arquivo comumente têm problemas de correspondência
4. Problemas de codificação de caracteres: Códigos de caracteres específicos que causam diffs

Histórico Local de Ferramentas e Logs de Auditoria

O Desktop Commander mantém registros de chamadas de ferramentas localmente na máquina que executa o servidor MCP. Esses arquivos locais são separados da telemetria opcional e não são um log de auditoria histórico no lado do servidor.

claude_tool_call.log — log de argumentos local

Cada chamada de ferramenta manipulada pelo servidor MCP local é anexada como uma linha de texto contendo um timestamp ISO, o nome da ferramenta e os argumentos serializados em JSON. Os argumentos não são editados ou sanitizados antes de serem gravados neste arquivo local, portanto, podem conter texto de comando, caminhos de arquivo ou outros valores sensíveis passados às ferramentas. As saídas das ferramentas não são gravadas neste arquivo.

O arquivo ativo é rotacionado quando atinge 10 MB. O arquivo anterior é renomeado usando um timestamp, por exemplo claude_tool_call_2026-09-07_14-32-10.log, e um novo claude_tool_call.log é criado. Os arquivos rotacionados não são excluídos automaticamente pelo registrador.

Locais:

• macOS/Linux: ~/.claude-server-commander/claude_tool_call.log
• Windows: %USERPROFILE%\.claude-server-commander\claude_tool_call.log

tool-history.jsonl — histórico recente de chamadas de ferramentas

O Desktop Commander também mantém um histórico JSON Lines usado por get_recent_tool_calls. Cada registro contém o timestamp, nome da ferramenta, argumentos, duração e o resultado retornado. Este histórico é carregado do disco na inicialização, para que o histórico recente possa sobreviver a uma reinicialização do servidor MCP.

Para manter este histórico limitado:

• No máximo as 1.000 chamadas mais recentes são mantidas em memória.
• A saída armazenada é limitada a 4 KiB por registro; saídas maiores são substituídas por um marcador de omissão.
• O arquivo em disco é reduzido quando cresce além de 5 MiB, mantendo aproximadamente os 4 MiB mais recentes.
• Na inicialização, um histórico com mais de 2.000 registros é reescrito para os 1.000 registros mais recentes.
• get_recent_tool_calls e track_ui_event são excluídos deste histórico JSONL.

Locais:

• macOS/Linux: ~/.claude-server-commander/tool-history.jsonl
• Windows: %USERPROFILE%\.claude-server-commander\tool-history.jsonl

Chamadas remotas e retenção no lado do servidor

Chamadas executadas através do Remote Desktop Commander ainda são manipuladas pelo servidor MCP local e usam os mesmos arquivos de histórico local acima. O serviço Remote Desktop Commander atualmente não retém argumentos de comando ou resultados de comando como uma trilha de auditoria histórica no lado do servidor após a conclusão da execução.

Esses arquivos de histórico local também são separados da telemetria opcional do Desktop Commander. Os arquivos em si não são enviados como telemetria. Consulte Data Collection & Privacy e PRIVACY.md para detalhes de telemetria.

Manipulação de Comandos de Longa Duração

Para comandos que podem demorar:

Gerenciamento de Configuração

⚠️ Avisos de Segurança Importantes

Para informações abrangentes de segurança e relato de vulnerabilidades: Consulte SECURITY.md

1. Limitações de segurança conhecidas: Restrições de diretório e bloqueio de comandos podem ser contornados por vários métodos, incluindo symlinks, substituição de comandos e caminhos absolutos ou execução de código

2. Sempre altere a configuração em uma janela de chat separada de onde você está fazendo seu trabalho real. O Claude pode às vezes tentar modificar definições de configuração (como allowedDirectories) se encontrar restrições de acesso ao sistema de arquivos.

3. A definição allowedDirectories atualmente só restringe operações do sistema de arquivos, não comandos de terminal. Comandos de terminal ainda podem acessar arquivos fora dos diretórios permitidos.

4. Para segurança em produção: Use a instalação Docker que fornece isolamento completo do seu sistema host.

Ferramentas de Configuração

Você pode gerenciar a configuração do servidor usando as ferramentas fornecidas:

// Get the entire config
get_config({})

// Set a specific config value
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })

// Set multiple config values using separate calls
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })

A configuração é salva em config.json no diretório de trabalho do servidor e persiste entre reinicializações do servidor.

Entendendo fileWriteLineLimit

A definição fileWriteLineLimit controla quantas linhas podem ser gravadas em uma única operação write_file (padrão: 50 linhas). Este limite existe por várias razões importantes:

Por que o limite existe:

• IAs são desperdiçadoras com tokens: Em vez de fazer duas pequenas edições em um arquivo, as IAs podem decidir reescrever tudo. Estamos tentando forçar as IAs a fazerem coisas em mudanças menores, pois isso economiza tempo e tokens
• Limites de mensagens UX do Claude: Existem limites dentro de uma mensagem e clicar em "Continuar" não funciona realmente. O que estamos tentando aqui é fazer a IA trabalhar em blocos menores para que, quando você atingir esse limite, vários blocos tenham sido concluídos e esse trabalho não seja perdido — ele só precisa recomeçar do último bloco

Definindo o limite:

// You can set it to thousands if you want
set_config_value({ "key": "fileWriteLineLimit", "value": 1000 })

// Or keep it smaller to force more efficient behavior
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })

Valor máximo: Você pode defini-lo para milhares se quiser — não há restrição técnica.

Melhores práticas:

• Mantenha o padrão (50) para incentivar o comportamento eficiente da IA e evitar desperdício de tokens
• O sistema sugere automaticamente o particionamento quando os limites são excedidos
• Blocos menores significam menos trabalho perdido quando o Claude atinge os limites de mensagem

Melhores Práticas

1. Crie um chat dedicado para mudanças de configuração: Faça todas as suas mudanças de configuração em um chat e depois inicie um novo chat para seu trabalho real.

2. Tenha cuidado com allowedDirectories vazio: Definir isso para um array vazio ([]) concede acesso a todo o seu sistema de arquivos para operações de arquivo.

3. Use caminhos específicos: Em vez de usar caminhos amplos como /, especifique diretórios exatos que você deseja acessar.

4. Sempre verifique a configuração após mudanças: Use get_config({}) para confirmar que suas mudanças foram aplicadas corretamente.

Opções de Linha de Comando

O Desktop Commander suporta várias opções de linha de comando para personalizar o comportamento:

Desativar Onboarding

Por padrão, o Desktop Commander mostra prompts de onboarding úteis para novos usuários (aqueles com menos de 10 chamadas de ferramentas). Você pode desativar esse comportamento:

# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# For npx installations, modify your claude_desktop_config.json:
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest",
        "--no-onboarding"
      ]
    }
  }
}

Quando o onboarding é desativado automaticamente:

• Quando o nome do cliente MCP está definido como "desktop-commander"
• Ao usar o sinalizador --no-onboarding
• Após os usuários usarem prompts de onboarding ou fazerem 10+ chamadas de ferramentas

Informações de depuração: O servidor registrará quando o onboarding for desativado: "Onboarding disabled via --no-onboarding flag"

Usando Diferentes Shells

Você pode especificar qual shell usar para execução de comandos:

// Using default shell (bash or system default)
execute_command({ "command": "echo $SHELL" })

// Using zsh specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })

// Using bash specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })

Isso permite que você use recursos específicos do shell ou mantenha ambientes consistentes entre comandos.

1. execute_command retorna após o tempo limite com a saída inicial
2. O comando continua em segundo plano
3. Use read_output com PID para obter nova saída
4. Use force_terminate para parar se necessário

Depuração

Se você precisar depurar o servidor, pode instalá-lo em modo de depuração:

# Using npx
npx @wonderwhy-er/desktop-commander@latest setup --debug

# Or if installed locally
npm run setup:debug

Isso irá:

1. Configurar o Claude para usar um servidor separado "desktop-commander"
2. Habilitar o protocolo do inspetor Node.js com o sinalizador --inspect-brk=9229
3. Pausar a execução no início até que um depurador se conecte
4. Habilitar variáveis de ambiente de depuração adicionais

Para conectar um depurador:

• No Chrome, visite chrome://inspect e procure a instância Node.js
• No VS Code, use a configuração de depuração "Attach to Node Process"
• Outros IDEs/ferramentas podem ter opções semelhantes de "anexar" para depuração Node.js

Notas importantes de depuração:

• O servidor pausará na inicialização até que um depurador se conecte (devido ao sinalizador --inspect-brk)
• Se você não vir atividade durante a depuração, certifique-se de estar conectado ao processo Node.js correto
• Vários processos Node podem estar em execução; conecte-se ao que está na porta 9229
• O servidor de depuração é identificado como "desktop-commander-debug" na lista de servidores MCP do Claude

Solução de problemas:

• Se o Claude expirar ao tentar usar o servidor de depuração, seu depurador pode não estar conectado corretamente
• Quando conectado corretamente, o processo continuará a execução após atingir o primeiro ponto de interrupção
• Você pode adicionar pontos de interrupção adicionais no seu IDE uma vez conectado

Integração com Model Context Protocol

Este projeto estende o MCP Filesystem Server para habilitar:

• Suporte a servidor local no Claude Desktop
• Execução completa de comandos do sistema
• Gerenciamento de processos
• Operações de arquivo
• Edição de código com blocos de busca/substituição

Criado como parte da exploração de MCPs do Claude: https://youtube.com/live/TlbjFDbl5Us

Apoie o Desktop Commander

❤️ Hall da Fama dos Apoiadores

Apoiadores generosos são destacados aqui. Obrigado por ajudar a tornar este projeto possível!

Jon Richards

Matija Stepanic

Website

Visite nosso site oficial em https://desktopcommander.app/ para obter as informações mais recentes, documentação e atualizações.

Mídia

Saiba mais sobre este projeto por meio destes recursos:

Artigo

Claude com MCPs substituiu Cursor & Windsurf. Como isso aconteceu? - Uma exploração detalhada de como o Claude com recursos de Model Context Protocol está mudando os fluxos de trabalho dos desenvolvedores.

Vídeo

Tutorial em Vídeo do Claude Desktop Commander - Assista a como configurar e usar o Commander de forma eficaz.

Publicação no AnalyticsIndiaMag

Este Desenvolvedor Abandonou Windsurf e Cursor Usando Claude com MCPs

Comunidade

Junte-se ao nosso servidor no Discord para obter ajuda, compartilhar feedback e conectar-se com outros usuários.

Depoimentos

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgztdHvDMqTb9jiqnf54AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg

https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e

Se você acha este projeto útil, considere dar uma ⭐ estrela no GitHub! Isso ajuda outros a descobrirem o projeto e incentiva o desenvolvimento contínuo.

Aceitamos contribuições da comunidade! Se você encontrou um bug, tem uma solicitação de recurso ou quer contribuir com código, veja como você pode ajudar:

• Encontrou um bug? Abra uma issue em github.com/wonderwhy-er/DesktopCommanderMCP/issues
• Tem uma ideia de recurso? Envie uma solicitação de recurso na seção de issues
• Quer contribuir com código? Faça um fork do repositório, crie uma branch e envie um pull request
• Perguntas ou discussões? Inicie uma discussão na aba GitHub Discussions

Todas as contribuições, grandes ou pequenas, são muito apreciadas!

Se você acha esta ferramenta valiosa para o seu fluxo de trabalho, considere apoiar o projeto.

Perguntas Frequentes

Aqui estão respostas para algumas perguntas comuns. Para um FAQ mais abrangente, consulte nosso documento de FAQ detalhado.

O que é o Desktop Commander?

É uma ferramenta MCP que permite ao Claude Desktop acessar seu sistema de arquivos e terminal, transformando o Claude em um assistente versátil para codificação, automação, exploração de bases de código e muito mais.

Como isso é diferente do Cursor/Windsurf?

Diferente de ferramentas focadas em IDE, o Claude Desktop Commander oferece uma abordagem centrada em soluções que funciona com todo o seu sistema operacional, não apenas dentro de um ambiente de codificação. O Claude lê arquivos por completo em vez de dividi-los em partes, pode trabalhar em vários projetos simultaneamente e executa alterações de uma só vez, sem exigir revisão constante.

Preciso pagar por créditos de API?

Não. Esta ferramenta funciona com a assinatura padrão Pro do Claude Desktop ($20/mês), não com chamadas de API, então você não terá custos adicionais além da taxa de assinatura.

O Desktop Commander é atualizado automaticamente?

Sim, quando instalado via npx ou Smithery, o Desktop Commander é atualizado automaticamente para a versão mais recente quando você reinicia o Claude. Nenhum processo de atualização manual é necessário.

Quais são os casos de uso mais comuns?

• Explorar e entender bases de código complexas
• Gerar diagramas e documentação
• Automatizar tarefas em todo o seu sistema
• Trabalhar com vários projetos simultaneamente
• Fazer alterações cirúrgicas no código com controle preciso

Estou tendo problemas para instalar ou usar a ferramenta. Onde posso obter ajuda?

Junte-se ao nosso servidor no Discord para suporte da comunidade, verifique as issues no GitHub para problemas conhecidos ou revise o FAQ completo para dicas de solução de problemas. Você também pode visitar a seção de FAQ do nosso site para uma experiência mais amigável. Se encontrar um novo problema, considere abrir uma issue no GitHub com detalhes sobre o seu problema.

Como reporto vulnerabilidades de segurança?

Crie uma Issue no GitHub com informações detalhadas sobre quaisquer vulnerabilidades de segurança que você descobrir. Consulte nossa Política de Segurança para diretrizes completas sobre divulgação responsável.

Coleta de Dados e Privacidade

O Desktop Commander coleta telemetria limitada e pseudônima para melhorar a ferramenta. Não coletamos conteúdos de arquivos, caminhos de arquivos ou argumentos de comandos como telemetria.

Isso é separado do histórico local de ferramentas e logs de auditoria, que permanecem na máquina que executa o Desktop Commander e podem conter argumentos de ferramentas e prévias limitadas de resultados.

Opt-out: Peça ao Claude para "desativar a telemetria do Desktop Commander" ou defina "telemetryEnabled": false na sua configuração.

Para detalhes completos, consulte nossa Política de Privacidade.

Verificações

Licença

MIT