Secure Filesystem MCP Server

🚀 Overview

This is a secure Model Context Protocol (MCP) server implementation that provides controlled filesystem access for AI models. It allows Large Language Models to securely read, write, and manipulate files within explicitly defined allowed directories.

This project is a Go implementation of the original Filesystem MCP server from the Model Context Protocol project developed by Anthropic, with additional editor tools to match Claude's trained expectations.

📁 Repository

This project is part of the PUBLIC-Golang-MCP-Servers repository, which contains various MCP server implementations in Go.

✨ Features

• Filesystem Tools:
  • Read and write files securely
  • Create and list directories
  • Move/rename files and directories
  • Search for files matching patterns
  • Get detailed file metadata
• Editor Tools (NEW):
  • str_replace: Surgical string replacement with validation
  • insert: Insert text at specific line numbers
  • undo_edit: Rollback file changes with automatic backups

🔧 Editor Tools Extension

This server includes editor tools that align with Claude Sonnet's trained expectations. These tools address issue #4027 where Claude attempts to use editing tools that don't exist in standard MCP Desktop environments.

Why this matters: Claude Sonnet has been trained with certain file editing primitives as part of Anthropic's computer use feature. When these aren't available, users experience failed tool calls and degraded workflows. These editor tools bridge that gap.

🧰 Available Tools

Filesystem Tools

Tool Name	Description
read_file	Read the complete contents of a file
read_multiple_files	Read multiple files at once
write_file	Create or overwrite a file
create_directory	Create a new directory
list_directory	List contents of a directory
move_file	Move or rename files and directories
search_files	Search for files matching a pattern
get_file_info	Get metadata about a file
list_allowed_directories	List all allowed directories

Editor Tools

Tool Name	Description
str_replace	Replace exact string in file (must appear once)
insert	Insert text after specified line number
undo_edit	Undo last edit to a file (automatic backup restoration)

⚙️ Configuration

The server uses a config.json file which should be placed in the same directory as the executable or in the current working directory:

{
  "allowedDirectories": [
    "C:\\Users\\Username\\AppData\\Roaming\\Claude",
    "C:\\Users\\Username\\Documents",
    "D:\\Projects"
  ]
}

If the config.json file doesn't exist, a default one will be created with the current directory as the allowed directory.

🚀 Getting Started

Prerequisites

• Go 1.21 or higher (only for building from source)
• Basic understanding of MCP architecture

Installation

Download Pre-built Binaries

Download the latest release for your platform from the Releases page.

Linux (x86_64):

wget https://github.com/LaurieRhodes/mcp-filesystem-go/releases/latest/download/mcp-filesystem-linux-amd64
chmod +x mcp-filesystem-linux-amd64
sudo mkdir -p /usr/local/bin/mcp-servers/filesystem
sudo mv mcp-filesystem-linux-amd64 /usr/local/bin/mcp-servers/filesystem/mcp-filesystem

# Create config file with your allowed directories
sudo tee /usr/local/bin/mcp-servers/filesystem/config.json > /dev/null <<'EOF'
{
  "allowedDirectories": [
    "/home",
    "/tmp"
  ]
}
EOF

macOS (Apple Silicon):

wget https://github.com/LaurieRhodes/mcp-filesystem-go/releases/latest/download/mcp-filesystem-darwin-arm64
chmod +x mcp-filesystem-darwin-arm64
sudo mkdir -p /usr/local/bin/mcp-servers/filesystem
sudo mv mcp-filesystem-darwin-arm64 /usr/local/bin/mcp-servers/filesystem/mcp-filesystem

# Create config file with your allowed directories
sudo tee /usr/local/bin/mcp-servers/filesystem/config.json > /dev/null <<'EOF'
{
  "allowedDirectories": [
    "/Users/username/Documents",
    "/Users/username/Projects"
  ]
}
EOF

Windows:

Download the .exe file and place it in a directory with a config.json file:

{
  "allowedDirectories": [
    "C:\\Users\\Username\\Documents",
    "C:\\Users\\Username\\Projects"
  ]
}

Building from Source

Standard Build (Windows)

# Clone the repository
git clone https://github.com/LaurieRhodes/mcp-filesystem-go.git
cd mcp-filesystem-go

# Build the server
go build -o mcp-filesystem-go.exe ./cmd/server

# Run the server (will use config.json)
mcp-filesystem-go.exe

Static Build for Linux (Recommended)

On Linux systems, it's recommended to build with static linking to avoid shared library dependency issues (e.g., libgo.so.23 errors):

# Clone the repository
git clone https://github.com/LaurieRhodes/mcp-filesystem-go.git
cd mcp-filesystem-go

# Build with static linking (no external dependencies)
CGO_ENABLED=0 go build -o mcp-filesystem-go -ldflags="-s -w" ./cmd/server

# Verify static linking (should show "not a dynamic executable")
ldd mcp-filesystem-go

# Make executable and run
chmod +x mcp-filesystem-go
./mcp-filesystem-go

Why static linking? When you compile Go programs on Linux with dynamic linking, they depend on specific versions of shared libraries (like libgo.so.23). Static linking produces a self-contained binary that runs on any Linux system without requiring these libraries to be installed.

MCP Client Configuration

The server requires a config.json file in the same directory as the executable to specify allowed directories. This design allows MCP servers to be shared between multiple clients rather than managing configuration within each client.

In your MCP client configuration (e.g., Claude Desktop), reference the server binary:

Linux/macOS Example

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/mcp-servers/filesystem/mcp-filesystem"
    }
  }
}

Windows Example

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\path\\to\\mcp-filesystem.exe"
    }
  }
}

Note: Update the paths in your config.json file (located next to the executable) to match your allowed directories.

📊 Implementation Details

This server is built with Go and follows the Model Context Protocol specifications:

• Transport: Uses stdio for communication (reading JSON-RPC messages from stdin and writing responses to stdout)
• Modular Design: Clean separation between MCP protocol handling, filesystem operations, and editor operations
• Comprehensive Error Handling: Detailed error messages for easier debugging
• Automatic Backups: Editor operations create timestamped backups before modifications

📜 License

This MCP server is licensed under the original Anthropic MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

👏 Attribution

This project is a port of the original Filesystem MCP server developed by Anthropic, PBC, which is part of the Model Context Protocol project. The original Node.js implementation is available at @modelcontextprotocol/server-filesystem.

The editor tools extension addresses community-identified gaps in Claude Desktop's MCP tool availability.

🤝 Contributing

This source code is provided as example code and not intended to become an active project. Feel free to fork and extend for your needs.