MCP Filesystem Server

MCP Filesystem Server

Secure asynchronous file system access via the Model Context Protocol

View on GitHub
552
Stars
87
Forks
552
Watchers
18
Issues
MCP Filesystem Server provides secure access to local files and directories through a standardized interface following the Model Context Protocol (MCP). It offers a set of tools for reading, writing, modifying, searching, and managing files and directories, with robust safeguards for path validation, symlink handling, and directory access. Designed to be used as a standalone server or integrated as a Go library, it facilitates safe and efficient programmatic file operations for AI-model-driven agents.

Key Features

Secure access to specified directories with path validation
Comprehensive file operations including read, write, copy, move, delete, and modify
Directory management: list, create, hierarchical tree view
Recursive search for files, directories, and file contents
Retrieve file and directory metadata
Returns list of allowed directories for controlled access
Symlink resolution with security checks
MIME type detection for files
Inline and base64 encoding support for file content
Configurable size limits and recursion depths

Use Cases

Granting controlled file system access to AI agents or automated tools
Securely reading, writing, or modifying files via an API
Automated directory tree inspection or inventory reporting
Bulk search and retrieval of files matching patterns or contents
Data ingestion or generation workflows needing sandboxed file operations
Programmatic backup, copy, or migration of files and directories
Validating or extracting metadata for audit and traceability purposes
Enforcing file system security boundaries in application sandboxes
Automated cleaning or pruning of files and folders
Building file management features into custom AI-model-driven products

README

MCP Filesystem Server

This MCP server provides secure access to the local filesystem via the Model Context Protocol (MCP).

Components

Resources

  • file://
    • Name: File System
    • Description: Access to files and directories on the local file system

Tools

File Operations

  • read_file

    • Read the complete contents of a file from the file system
    • Parameters: path (required): Path to the file to read

  • read_multiple_files

    • Read the contents of multiple files in a single operation
    • Parameters: paths (required): List of file paths to read

  • write_file

    • Create a new file or overwrite an existing file with new content
    • Parameters: path (required): Path where to write the file, content (required): Content to write to the file

  • copy_file

    • Copy files and directories
    • Parameters: source (required): Source path of the file or directory, destination (required): Destination path

  • move_file

    • Move or rename files and directories
    • Parameters: source (required): Source path of the file or directory, destination (required): Destination path

  • delete_file

    • Delete a file or directory from the file system
    • Parameters: path (required): Path to the file or directory to delete, recursive (optional): Whether to recursively delete directories (default: false)

  • modify_file

    • Update file by finding and replacing text using string matching or regex
    • Parameters: path (required): Path to the file to modify, find (required): Text to search for, replace (required): Text to replace with, all_occurrences (optional): Replace all occurrences (default: true), regex (optional): Treat find pattern as regex (default: false)

Directory Operations

  • list_directory

    • Get a detailed listing of all files and directories in a specified path
    • Parameters: path (required): Path of the directory to list

  • create_directory

    • Create a new directory or ensure a directory exists
    • Parameters: path (required): Path of the directory to create

  • tree

    • Returns a hierarchical JSON representation of a directory structure
    • Parameters: path (required): Path of the directory to traverse, depth (optional): Maximum depth to traverse (default: 3), follow_symlinks (optional): Whether to follow symbolic links (default: false)

Search and Information

  • search_files

    • Recursively search for files and directories matching a pattern
    • Parameters: path (required): Starting path for the search, pattern (required): Search pattern to match against file names

  • search_within_files

    • Search for text within file contents across directory trees
    • Parameters: path (required): Starting directory for the search, substring (required): Text to search for within file contents, depth (optional): Maximum directory depth to search, max_results (optional): Maximum number of results to return (default: 1000)

  • get_file_info

    • Retrieve detailed metadata about a file or directory
    • Parameters: path (required): Path to the file or directory

  • list_allowed_directories

    • Returns the list of directories that this server is allowed to access
    • Parameters: None

Features

  • Secure access to specified directories
  • Path validation to prevent directory traversal attacks
  • Symlink resolution with security checks
  • MIME type detection
  • Support for text, binary, and image files
  • Size limits for inline content and base64 encoding

Getting Started

Installation

Using Go Install

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

Usage

As a standalone server

Start the MCP server with allowed directories:

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

As a library in your Go project

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)
	}
}

Usage with Model Context Protocol

To integrate this server with apps that support MCP:

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

Docker

Running with Docker

You can run the Filesystem MCP server using Docker:

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

Docker Configuration with MCP

To integrate the Docker image with apps that support MCP:

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

If you need changes made inside the container to reflect on the host filesystem, you can mount a volume. This allows the container to access and modify files on the host system. Here's an example:

json
{
  "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"
      ]
    }
  }
}

License

See the LICENSE file for details.

Star History

Star History Chart

Repository Owner

mark3labs
mark3labs

Organization

Repository Details

Language Go
Default Branch main
Size 89 KB
Contributors 7
License MIT License
MCP Verified Nov 12, 2025

Programming Languages

Go
99.44%
Dockerfile
0.56%

Tags

file management API server Access control

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

We respect your privacy. Unsubscribe at any time.

Related MCPs

Discover similar Model Context Protocol servers

  • Filestash

    Filestash

    A modular, extensible file manager with robust API and LLM Model Context Protocol (MCP) integration.

    Filestash is a versatile file manager that supports a wide range of backends including FTP, SFTP, WebDAV, S3, SMB, and popular cloud storage services such as Dropbox and Google Drive. It features a plugin-driven architecture and workflow engine for customization and automation and offers built-in viewers for images, music, and video. Filestash provides an API interface and explicit LLM integration via Model Context Protocol (MCP), enabling advanced file management automation and AI-driven workflows.

    • ⭐ 13,013
    • MCP
    • mickael-kerjean/filestash
  • fast-filesystem-mcp

    fast-filesystem-mcp

    Advanced filesystem operations and large file management for Claude Desktop environments.

    fast-filesystem-mcp provides fast, memory-efficient file operations tailored for Claude Desktop using the Model Context Protocol. It supports chunked and streaming reads/writes, backup and recovery features, and advanced directory and file management tools. The implementation includes settings for debugging, logging, and error handling to seamlessly integrate with Claude Desktop's workflow.

    • ⭐ 26
    • MCP
    • efforthye/fast-filesystem-mcp
  • PDF Tools MCP

    PDF Tools MCP

    Comprehensive PDF manipulation via MCP protocol.

    PDF Tools MCP provides an extensive suite of PDF manipulation operations using the Model Context Protocol framework. It supports both local and remote PDF tasks, such as rendering pages, merging, extracting metadata, retrieving text, and combining documents. The tool registers endpoints through the MCP protocol, enabling seamless server-based PDF processing for various clients. Built with Python, it emphasizes secure handling and compatibility with Claude Desktop via the Smithery ecosystem.

    • ⭐ 31
    • MCP
    • danielkennedy1/pdf-tools-mcp
  • Netwrix Access Analyzer MCP Server

    Netwrix Access Analyzer MCP Server

    An MCP server integrating enterprise access analysis tools with Claude Desktop.

    Netwrix Access Analyzer MCP Server provides a Model Context Protocol (MCP) server designed for integration with Claude Desktop. It enables secure and dynamic access to Active Directory, SQL Server databases, and file system data for auditing and analysis. The server offers a range of tools for effective group membership discovery, permission analysis, sensitive data detection, and more. It streamlines enterprise security assessments by standardizing context-sharing for AI-driven solutions.

    • ⭐ 1
    • MCP
    • netwrix/mcp-server-naa
  • Monarch Money MCP Server

    Monarch Money MCP Server

    Read-only Model Context Protocol server for Monarch Money financial data.

    Provides a Model Context Protocol (MCP) server that enables read-only access to Monarch Money financial accounts, transactions, budgets, and cashflow data. Designed primarily for secure integration with AI assistants such as Claude Desktop, it supports authentication, session persistence, and multi-factor authentication. The implementation allows for detailed transaction analysis, budgeting, and cashflow insights without altering user data, supporting various financial inquiries through standardized endpoints and tools.

    • ⭐ 0
    • MCP
    • carsol/monarch-mcp-server
  • Contentful MCP Server

    Contentful MCP Server

    Community-driven MCP server for advanced Contentful content management.

    Contentful MCP Server is an implementation of the Model Context Protocol (MCP) designed to provide seamless integration with Contentful’s Content Management API. It enables full CRUD operations for entries and assets, facilitates comment and space management, and supports bulk asynchronous operations. With features like smart pagination and localization, it aims to optimize LLM context handling and streamline workflows for content-rich applications.

    • ⭐ 61
    • MCP
    • ivo-toby/contentful-mcp
    • View all Alternatives

    Didn't find tool you were looking for?

    Be as detailed as possible for better results