Filesystem MCP Server for WSL

Um servidor de sistema de arquivos para o Subsistema Windows para Linux (WSL), usando comandos nativos para operações de arquivo mais rápidas.

GitHub
14
Experimente este MCPPatrocinado

Documentação

⚠️ INFORMAÇÃO IMPORTANTE:
O Filesystem MCP Server original já pode acessar arquivos do WSL simplesmente usando o caminho de rede \\wsl.localhost\DistributionName como parâmetro na configuração.
Exemplo:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "\\\\wsl.localhost\\Debian",
        "C:\\path\\to\\other\\allowed\\dir"
      ]
    }
  }
}

No entanto, este projeto oferece uma implementação alternativa especificamente otimizada para distribuições Linux do WSL.

Enquanto o servidor oficial funciona percorrendo diretórios recursivamente usando o módulo fs do Node.js, esta implementação utiliza comandos nativos do Linux dentro do WSL (como find, grep, etc.), tornando as operações de listagem de arquivos e busca de conteúdo significativamente mais rápidas.

Isso pode ser especialmente útil ao lidar com grandes árvores de diretórios ou quando o desempenho da busca é crítico.

Portanto, embora o caminho de rede nativo possa ser mais simples para muitos casos de uso, este projeto continua sendo uma solução valiosa para usuários de WSL que buscam melhor desempenho ou controle personalizado sobre a lógica de indexação e busca.

Filesystem MCP Server for WSL

npm version License: MIT

Servidor Node.js que implementa o Model Context Protocol (MCP), especificamente projetado para operações de sistema de arquivos no Windows Subsystem for Linux (WSL).
Este projeto é um fork do Filesystem MCP Server original, mas completamente reimaginado para ambientes WSL.
Diferente do projeto original, que lida com operações genéricas de arquivos, esta versão foca exclusivamente na interação perfeita entre Windows e distribuições Linux sob o WSL.
Ambos os projetos são compatíveis e podem rodar em paralelo no mesmo sistema.

Recursos

  • Acesse qualquer distribuição WSL a partir do Windows
  • Leia/escreva arquivos no WSL a partir do host Windows
  • Crie/liste/exclua diretórios no WSL
  • Mova arquivos/diretórios pelo sistema de arquivos do WSL
  • Pesquise arquivos dentro do WSL
  • Obtenha metadados de arquivos do sistema de arquivos do WSL
  • Suporte a múltiplas distribuições WSL

Nota: O servidor só permite operações dentro dos diretórios especificados via args.

API

Recursos

  • wsl -d <distrib>: Comando para operações em distribuições WSL

Ferramentas

  • read_file

    • Lê o conteúdo completo de um arquivo do WSL
    • Entrada: path (string)
    • Lê o conteúdo como texto UTF-8

  • read_file_by_parts

    • Lê arquivos grandes em partes de aproximadamente 95.000 caracteres
    • Entradas:
      • path (string)
      • part_number (inteiro positivo: 1, 2, 3, etc.)
    • Recursos:
      • A parte 1 começa do início do arquivo
      • As partes subsequentes se alinham aos limites das linhas (ajuste máximo de 300 caracteres)
      • Retorna erro com o tamanho real do arquivo se a parte solicitada não existir
      • Útil para arquivos grandes demais para serem lidos em uma única operação

  • read_multiple_files

    • Lê vários arquivos simultaneamente do WSL
    • Entrada: paths (string[])
    • Falhas de leitura não interrompem a operação inteira

  • write_file

    • Cria ou sobrescreve um arquivo no WSL (use com cuidado)
    • Entradas:
      • path (string)
      • content (string)

  • edit_file

    • Edições seletivas com correspondência avançada de padrões e formatação
    • Entradas:
      • path (string)
      • edits (array de { oldText, newText })
      • dryRun (booleano, opcional)
    • Recursos:
      • Correspondência em várias linhas
      • Preservação de indentação
      • Pré-visualização de diff no estilo Git
      • Modo simulação (dry run) não-destrutivo

  • create_directory

    • Cria ou garante a existência de um diretório no WSL
    • Entrada: path (string)

  • list_directory

    • Lista o conteúdo do diretório com prefixos [FILE] ou [DIR]
    • Entrada: path (string)

  • directory_tree

    • Visão em árvore JSON recursiva do conteúdo
    • Entrada: path (string)

  • move_file

    • Move ou renomeia arquivos/diretórios
    • Entradas:
      • source (string)
      • destination (string)

  • search_files

    • Busca recursiva por nome
    • Entradas:
      • path (string)
      • pattern (string)
      • excludePatterns (string[], opcional)

  • search_in_files

    • Busca padrões de texto dentro de arquivos recursivamente
    • Entradas:
      • path (string) - diretório raiz para busca
      • pattern (string) - texto ou padrão regex para encontrar
      • caseInsensitive (booleano, opcional) - busca sem diferenciar maiúsculas de minúsculas
      • isRegex (booleano, opcional) - tratar o padrão como regex
      • includePatterns (string[], opcional) - padrões de arquivo para incluir (ex.: *.js)
      • excludePatterns (string[], opcional) - padrões de arquivo para excluir
      • maxResults (número, opcional, padrão: 1000) - máximo de resultados a retornar
      • contextLines (número, opcional, padrão: 0) - linhas de contexto antes/depois
    • Recursos:
      • Lida com todos os caracteres especiais (apóstrofos, aspas, $, barras invertidas)
      • Suporta buscas por texto simples e expressões regulares
      • Mostra linhas correspondentes com caminhos de arquivo e números de linha
      • Exclui automaticamente diretórios .git, node_modules, .svn, .hg
      • Pode mostrar linhas de contexto ao redor das correspondências

  • get_file_info

    • Metadados detalhados
    • Entrada: path (string)
    • Retorna: tamanho, timestamps, tipo, permissões

  • list_allowed_directories

    • Lista todos os diretórios acessíveis ao servidor

  • list_wsl_distributions

    • Lista as distribuições disponíveis e mostra a ativa

Requisitos

Para usuários do Claude Desktop:
Nenhuma instalação adicional é necessária — basta configurar seu claude_desktop_config.json.

Pacote NPM:
O pacote está disponível no npm: mcp-server-wsl-filesystem

Para desenvolvimento:

  • Node.js (v18.0.0 ou superior)
  • TypeScript (incluído como dependência de desenvolvimento)

Instalando o Node.js no Windows

  1. Baixe o instalador do nodejs.org
  2. Execute-o e siga as instruções
  3. Verifique as versões:
node --version
npm --version

Uso

Antes de executar o servidor, você precisa compilar o projeto TypeScript:

npm install
npm run build

Execute o servidor especificando qual distribuição WSL usar (opcional) e quais diretórios expor:

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

Se nenhuma distribuição for especificada, a distribuição padrão do WSL será usada.

Exemplos

Acesse a distribuição Ubuntu-20.04:

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

Use a distribuição padrão:

node dist/index.js /home/user/documents

Uso com o Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

Opção 1: Usando uma distribuição WSL específica

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

Opção 2: Usando a distribuição WSL padrão

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

No segundo exemplo, o sistema usará sua distribuição WSL padrão sem que você precise especificá-la.

Diferenças em relação ao projeto original

Este fork adapta o Filesystem MCP Server original para funcionar com WSL ao:

  1. Substituir chamadas diretas ao sistema de arquivos do Node.js por execuções de comandos WSL
  2. Adicionar suporte para selecionar distribuições WSL específicas
  3. Implementar tradução de caminhos entre formatos Windows e Linux
  4. Melhorar o tratamento do conteúdo de arquivos para compatibilidade entre plataformas
  5. Adicionar ferramentas especializadas para gerenciamento do WSL

Licença

Este projeto é um fork do Filesystem MCP Server original criado pela equipe do Model Context Protocol.

Este servidor MCP para WSL é licenciado sob a Licença MIT, seguindo a licença do projeto original. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto original.