filesystem-mcp-server

Filesystem MCP server with Streamable HTTP transport support. Provides comprehensive filesystem operations through the Model Context Protocol.

Created as an alternative to the official MCP filesystem server with modern Streamable HTTP transport instead of deprecated SSE.

Features

• Streamable HTTP Transport - Modern MCP protocol
• 8 Filesystem Operations - Read, write, list, create, delete, move, and inspect files/directories
• Security First - Configurable root directory with path traversal protection
• Docker Ready - Multi-arch images (amd64/arm64) published to GHCR

Quick Start

Docker (Recommended)

docker pull ghcr.io/njbrake/filesystem-mcp-server:main

docker run -d \
  --name filesystem-mcp \
  -p 8123:8123 \
  -v /path/to/your/files:/data \
  ghcr.io/njbrake/filesystem-mcp-server:main

Available tags: main (latest), v* (releases), main-<sha> (commits)

Python with uv

cd filesystem-mcp-server
uv sync
uv run filesystem-mcp --allowed-root /path/to/files --port 8123

Server endpoint: http://localhost:8123/mcp

Command Line Options

Option	Default	Description
--port	8123	Port to listen on
--allowed-root	.	Root directory for filesystem operations

Available Tools

The server exposes 8 MCP tools for filesystem operations:

Tool	Description	Parameters
read_file	Read file contents as text	path
list_directory	List directory contents with metadata	path (optional, default: ".")
write_file	Create or overwrite a file	path, content
create_directory	Create directory (with parents)	path
delete_file	Delete a file	path
delete_directory	Delete directory	path, recursive (optional)
move_path	Move or rename file/directory	source, destination
get_file_info	Get file/directory metadata	path

All paths are relative to the configured --allowed-root.

Security

The --allowed-root parameter restricts all filesystem operations to the specified directory tree. Path validation prevents directory traversal attacks:

1. Paths are resolved relative to allowed root
2. Symlinks and .. components are canonicalized
3. Final path must be within allowed root
4. Attempts to escape are rejected (e.g., ../../../etc/passwd)

Important: Never run with system-critical directories as the allowed root.

Docker Details

Custom Configuration

# Different port
docker run -p 8000:8000 \
  -v /my/files:/data \
  ghcr.io/njbrake/filesystem-mcp-server:main \
  --allowed-root /data --port 8000

# Build locally
docker build -t filesystem-mcp-server .

Container Details

• Default port: 8123
• Default allowed root: /data
• Volume mount point: /data
• Multi-architecture: linux/amd64, linux/arm64

Testing

# List available tools
curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Read a file
curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"tools/call",
    "params":{
      "name":"read_file",
      "arguments":{"path":"README.md"}
    },
    "id":2
  }'

About MCP

This server implements the Model Context Protocol, an open protocol for seamless integration between LLM applications and external tools.

Uses Streamable HTTP transport (MCP spec 2025-03-26), the modern replacement for deprecated HTTP+SSE.