# 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](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) 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)

```bash
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

```bash
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

```bash
# 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

```bash
# 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](https://modelcontextprotocol.io/), 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.