filesystem

The Filesystem MCP Server provides a secure, sandboxed interface for AI agents to interact with your local filesystem. Built in Go with strict directory sandboxing, symlink attack prevention, and atomic writes, it exposes a suite of 17 file-related tools that let agents read, write, copy, move, delete, and inspect files and directories within explicitly allowed roots. The server is optimized for AI agents that need safe, programmatic access to code files, assets, or project directories while preserving system integrity. You can start the server with Docker and then issue the available tool calls to perform operations such as reading text, listing directories, or performing atomic writes, all while honoring the configured allowed paths.

Prerequisites:

• Docker installed and running
• Optional: Go installed if you want to build from source

Recommended installation (Docker):

1. Pull the prebuilt Docker image:

docker pull portertech/filesystem-mcp-server

2. Run the server with your allowed directories configured at runtime (example below shows how to expose an allowed root; adjust as needed):

docker run -i portertech/filesystem-mcp-server /path/to/allowed/dir

Alternative (Build from source):

# Install Go if not already installed
# Clone the repository
git clone https://github.com/portertech/filesystem-mcp-server.git
cd filesystem-mcp-server

# Build the binary
make build

# Run locally (example):
./filesystem /path/to/allowed/dir

Prebuilt binaries are also available on the GitHub Releases page for quick deployment.

Tips and common issues:

• Always start the server with at least one allowed root directory. All tool operations are restricted to these roots.
• If you enable verbose logging, you can better diagnose path resolution and symlink handling issues.
• Use read_text_file for reading large text files efficiently; it supports partial reads and line numbers for AI-friendly output.
• Ensure your environment respects file permissions; the server reports metadata including permissions to help you audit access.
• For write operations, atomic writes are used to prevent partial writes in case of interruptions.
• When using Docker, consider mounting a host directory as a volume and passing it as the allowed root to ensure persistence across restarts.