File System MCP Server

Um servidor para gerenciamento abrangente de arquivos e diretórios no sistema de arquivos local.

Documentação

File System MCP Server

Um poderoso servidor de gerenciamento de sistema de arquivos criado com FastMCP que fornece um conjunto abrangente de ferramentas para operações de arquivos e diretórios. Este servidor permite realizar diversas operações no sistema de arquivos por meio de uma API estruturada, tornando-o ideal para automação e integração com outros sistemas.

Suporte a Plataformas

O servidor foi projetado para funcionar em diferentes sistemas operacionais, mas com níveis variados de funcionalidade:

Windows

Suporte completo a recursos
Listagem de unidades
Acesso a pastas especiais
Tratamento de caminhos específico do Windows
Informações detalhadas do sistema

macOS/Linux

Operações básicas de arquivos
Operações de diretório
Pesquisa de arquivos e metadados
Informações básicas do sistema
Observação: alguns recursos específicos do Windows não estão disponíveis

Implementação Futura

Suporte Planejado para macOS

Tratamento nativo de caminhos para macOS
Recuperação de informações específicas do sistema macOS
Integração com recursos do sistema de arquivos do macOS
Suporte a atributos de arquivo específicos do macOS
Implementação de utilitários específicos do macOS (semelhante ao windows_utils.py)

Suporte Planejado para Linux

Tratamento nativo de caminhos para Linux
Recuperação de informações específicas do sistema Linux
Integração com recursos do sistema de arquivos do Linux
Suporte a permissões e atributos de arquivo do Linux
Implementação de utilitários específicos do Linux

Melhorias Multiplataforma

Sistema unificado de tratamento de caminhos
Detecção de unidades independente de plataforma
API consistente de informações do sistema
Atributos de arquivo padronizados entre plataformas
Monitoramento de eventos do sistema de arquivos multiplataforma
Sistema universal de coleção de arquivos

Cronograma

Fase 1: Melhorias básicas de compatibilidade multiplataforma
Fase 2: Implementações de recursos específicos da plataforma
Fase 3: Recursos avançados multiplataforma
Fase 4: Otimizações e refinamentos de desempenho

Recursos

Operações de Arquivo

Copiar arquivos com suporte a backup
Mover arquivos com suporte a backup
Excluir arquivos com verificações de segurança
Ler conteúdo de arquivos
Gravar conteúdo em arquivos
Obter informações do arquivo (tamanho, data de criação, data de modificação)
Pesquisar arquivos por padrão de nome
Criar coleções de arquivos para organizar arquivos relacionados

Operações de Diretório

Listar conteúdo de diretórios
Criar diretórios
Excluir diretórios
Listar diretórios recursivamente (estrutura em árvore)
Pesquisar diretórios por padrão de nome

Informações do Sistema

Obter informações do sistema (SO, CPU, memória, uso de disco)
Obter informações de disco (espaço total, espaço usado, espaço livre)
Obter informações de diretório (contagem de arquivos, tamanho total)

Estrutura do Projeto

file-system-mcp-server/
├── fs_server.py            # Main server implementation
├── windows_utils.py        # Windows-specific utilities (Windows only)
├── requirements.txt        # Project dependencies
└── test_prompts_example.md # Example test prompts

Armazenamento de Coleções

As coleções podem ser armazenadas em qualquer diretório especificado pelo usuário. Se nenhum local de armazenamento for especificado, as coleções serão armazenadas em um local padrão dentro do diretório data/collections do projeto.

Exemplo de uso:

# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])

# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")

Dependências

Dependências Necessárias

FastMCP
Pydantic
pywin32 (somente Windows)
WMI (somente Windows)

Para instalar as dependências:

pip install -r requirements.txt

Configuração

Clone o repositório:

git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server

Crie e ative um ambiente virtual:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instale as dependências:

pip install -r requirements.txt

Uso

Para instruções detalhadas de configuração do MCP em diferentes ambientes de desenvolvimento (Claude, Cursor, Windsurf), visite: Guia de Configuração do MCP

Integração com Claude

Para integrar o servidor File System MCP com o Claude, adicione o seguinte ao seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "file-system": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Encontrando o Caminho do Seu Python

Para encontrar o caminho do executável do Python, use o seguinte comando:

Windows (PowerShell):

(Get-Command python).Source

Windows (Prompt de Comando/Terminal):

where python

Linux/macOS (Terminal):

which python

Substitua /absolute/path/to/python pela saída do comando apropriado acima.

Exemplo de Configuração

Para Windows, sua configuração pode ser assim:

{
  "mcpServers": {
    "file-system": {
      "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
      "args": [
        "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Para macOS/Linux:

{
  "mcpServers": {
    "file-system": {
      "command": "/usr/local/bin/python3",
      "args": [
        "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
      ]
    }
  }
}

Após adicionar a configuração:

Salve o arquivo claude_desktop_config.json
Reinicie o Claude
Agora você pode usar as ferramentas do sistema de arquivos pedindo ao Claude para realizar operações de arquivo

Ferramentas Disponíveis

Operações de Arquivo

copy_file: Copiar um arquivo com backup opcional
move_file: Mover um arquivo com backup opcional
delete_file: Excluir um arquivo com verificações de segurança
read_file: Ler o conteúdo de um arquivo
write_file: Gravar conteúdo em um arquivo
get_file_info: Obter informações detalhadas do arquivo
search_files: Pesquisar arquivos por padrão de nome
create_collection: Criar uma coleção de arquivos

Operações de Diretório

list_directory: Listar conteúdo do diretório
create_directory: Criar um novo diretório
delete_directory: Excluir um diretório
list_directory_recursively: Exibir estrutura do diretório em formato de árvore
search_directories: Pesquisar diretórios por padrão de nome

Informações do Sistema

get_system_info: Obter informações do sistema
get_disk_info: Obter informações de uso de disco
get_directory_info: Obter estatísticas do diretório

Problemas Conhecidos

Os seguintes recursos estão atualmente enfrentando problemas e podem não funcionar como esperado:

Função de Exclusão de Arquivo
- A função delete_file pode falhar ao excluir arquivos corretamente em alguns casos
- Recomenda-se verificar manualmente a exclusão do arquivo ou usar métodos alternativos quando for crítico
- O problema está sob investigação e será corrigido em uma atualização futura
Função de Listagem de Unidades
- A função list_drives pode não detectar ou exibir corretamente todas as unidades disponíveis
- Algumas unidades podem estar ausentes na lista ou mostrar informações incorretas
- Esta é uma limitação conhecida e será tratada em atualizações futuras
Limitações Específicas da Plataforma
- Recursos específicos do Windows não estão disponíveis no macOS/Linux
- Algum tratamento de caminhos pode diferir entre plataformas
- A recuperação de informações do sistema varia por plataforma

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

Caminhos de arquivo inválidos
Arquivo/diretório não encontrado
Problemas de permissão
Limitações de espaço em disco
Operações inválidas
Erros específicos da plataforma

Segurança

Todas as operações de arquivo incluem validação de caminho
Os arquivos de backup são criados antes de operações destrutivas
O acesso às informações do sistema é restrito a operações seguras
As operações de arquivo são realizadas com tratamento adequado de erros

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído com FastMCP
Usa Pydantic para validação de dados
Inspirado em ferramentas modernas de gerenciamento de sistema de arquivos