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:
- Paths are resolved relative to allowed root
- Symlinks and
..components are canonicalized - Final path must be within allowed root
- 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.