MCP Filesystem Server

MCP Filesystem Server

Este servidor MCP fornece acesso seguro ao sistema de arquivos local por meio do Model Context Protocol (MCP).

Componentes

Recursos

• file://
  • Nome: File System
  • Descrição: Acesso a arquivos e diretórios no sistema de arquivos local

Ferramentas

Operações de Arquivo

• read_file

  • Lê o conteúdo completo de um arquivo do sistema de arquivos
  • Parâmetros: path (obrigatório): Caminho para o arquivo a ser lido

• read_multiple_files

  • Lê o conteúdo de vários arquivos em uma única operação
  • Parâmetros: paths (obrigatório): Lista de caminhos de arquivos a serem lidos

• write_file

  • Cria um novo arquivo ou sobrescreve um arquivo existente com novo conteúdo
  • Parâmetros: path (obrigatório): Caminho onde o arquivo será gravado, content (obrigatório): Conteúdo a ser gravado no arquivo

• copy_file

  • Copia arquivos e diretórios
  • Parâmetros: source (obrigatório): Caminho de origem do arquivo ou diretório, destination (obrigatório): Caminho de destino

• move_file

  • Move ou renomeia arquivos e diretórios
  • Parâmetros: source (obrigatório): Caminho de origem do arquivo ou diretório, destination (obrigatório): Caminho de destino

• delete_file

  • Exclui um arquivo ou diretório do sistema de arquivos
  • Parâmetros: path (obrigatório): Caminho para o arquivo ou diretório a ser excluído, recursive (opcional): Se deve excluir diretórios recursivamente (padrão: false)

• modify_file

  • Atualiza o arquivo localizando e substituindo texto usando correspondência de string ou regex
  • Parâmetros: path (obrigatório): Caminho para o arquivo a ser modificado, find (obrigatório): Texto a ser pesquisado, replace (obrigatório): Texto de substituição, all_occurrences (opcional): Substituir todas as ocorrências (padrão: true), regex (opcional): Tratar o padrão de busca como regex (padrão: false)

Operações de Diretório

• list_directory

  • Obtém uma listagem detalhada de todos os arquivos e diretórios em um caminho especificado
  • Parâmetros: path (obrigatório): Caminho do diretório a ser listado

• create_directory

  • Cria um novo diretório ou garante que um diretório exista
  • Parâmetros: path (obrigatório): Caminho do diretório a ser criado

• tree

  • Retorna uma representação JSON hierárquica de uma estrutura de diretórios
  • Parâmetros: path (obrigatório): Caminho do diretório a ser percorrido, depth (opcional): Profundidade máxima a ser percorrida (padrão: 3), follow_symlinks (opcional): Se deve seguir links simbólicos (padrão: false)

Pesquisa e Informações

• search_files

  • Pesquisa recursivamente arquivos e diretórios que correspondem a um padrão
  • Parâmetros: path (obrigatório): Caminho inicial para a pesquisa, pattern (obrigatório): Padrão de pesquisa para corresponder aos nomes de arquivos

• search_within_files

  • Pesquisa texto dentro do conteúdo de arquivos em árvores de diretórios
  • Parâmetros: path (obrigatório): Diretório inicial para a pesquisa, substring (obrigatório): Texto a ser pesquisado no conteúdo dos arquivos, depth (opcional): Profundidade máxima do diretório a ser pesquisado, max_results (opcional): Número máximo de resultados a retornar (padrão: 1000)

• get_file_info

  • Recupera metadados detalhados sobre um arquivo ou diretório
  • Parâmetros: path (obrigatório): Caminho para o arquivo ou diretório

• list_allowed_directories

  • Retorna a lista de diretórios aos quais este servidor tem permissão de acesso
  • Parâmetros: Nenhum

Recursos

• Acesso seguro a diretórios especificados
• Validação de caminho para prevenir ataques de travessia de diretório
• Resolução de links simbólicos com verificações de segurança
• Detecção de tipo MIME
• Suporte para arquivos de texto, binários e imagens
• Limites de tamanho para conteúdo inline e codificação base64

Primeiros Passos

Instalação

Usando Go Install

go install github.com/mark3labs/mcp-filesystem-server@latest

Uso

Como servidor autônomo

Inicie o servidor MCP com diretórios permitidos:

mcp-filesystem-server /path/to/allowed/directory [/another/allowed/directory ...]

Como biblioteca no seu projeto Go

package main

import (
	"log"
	"os"

	"github.com/mark3labs/mcp-filesystem-server/filesystemserver"
)

func main() {
	// Create a new filesystem server with allowed directories
	allowedDirs := []string{"/path/to/allowed/directory", "/another/allowed/directory"}
	fs, err := filesystemserver.NewFilesystemServer(allowedDirs)
	if err != nil {
		log.Fatalf("Failed to create server: %v", err)
	}

	// Serve requests
	if err := fs.Serve(); err != nil {
		log.Fatalf("Server error: %v", err)
	}
}

Uso com Model Context Protocol

Para integrar este servidor com aplicativos que suportam MCP:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem-server",
      "args": ["/path/to/allowed/directory", "/another/allowed/directory"]
    }
  }
}

Docker

Executando com Docker

Você pode executar o servidor MCP Filesystem usando Docker:

docker run -i --rm ghcr.io/mark3labs/mcp-filesystem-server:latest /path/to/allowed/directory

Configuração Docker com MCP

Para integrar a imagem Docker com aplicativos que suportam MCP:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mark3labs/mcp-filesystem-server:latest",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Se você precisar que alterações feitas dentro do contêiner sejam refletidas no sistema de arquivos do host, você pode montar um volume. Isso permite que o contêiner acesse e modifique arquivos no sistema host. Aqui está um exemplo:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--volume=/allowed/directory/in/host:/allowed/directory/in/container",
        "ghcr.io/mark3labs/mcp-filesystem-server:latest",
        "/allowed/directory/in/container"
      ]
    }
  }
}

Licença

Consulte o arquivo LICENSE para obter detalhes.