# bridgemcp-server-filesystem

Official BridgeMCP reference server — safe filesystem access for AI clients.

[![CI](https://github.com/Arsie-codes/bridgemcp-server-filesystem/actions/workflows/ci.yml/badge.svg)](https://github.com/Arsie-codes/bridgemcp-server-filesystem/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/bridgemcp-server-filesystem)](https://pypi.org/project/bridgemcp-server-filesystem/)
[![Python](https://img.shields.io/pypi/pyversions/bridgemcp-server-filesystem)](https://pypi.org/project/bridgemcp-server-filesystem/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Overview

`bridgemcp-server-filesystem` exposes ten filesystem tools to any MCP-compatible AI client (Claude Desktop, Cursor, etc.). It is the second official server in the BridgeMCP ecosystem and serves as the canonical reference implementation for filesystem access.

**Key safety features:**

- **Root confinement** — set `--root /workspace` to restrict all operations to that directory. Path traversal attacks (`../../etc/passwd`) and symlink escapes are blocked at the `Path.resolve()` level before any filesystem operation occurs.
- **Read-only mode** — set `--read-only` to expose a directory for inspection without permitting any writes.
- **File size limit** — set `--max-file-size-mb 10` to prevent accidentally reading large files.
- **Binary detection** — `read_file` detects binary files before decoding and returns a structured `is_binary=True` response instead of a `UnicodeDecodeError`.
- **Explicit delete confirmation** — `delete_path` requires `confirm=True` in every call. The configured root can never be deleted.

## Installation

```bash
pip install bridgemcp-server-filesystem
pip install 'bridgemcp-server-filesystem[mcp]'  # for running as an MCP server
```

## Quick start

**Programmatic use:**

```python
from bridgemcp_filesystem import create_app

app = create_app(root="/workspace", read_only=False, max_file_size_mb=10.0)
app.run()
```

**CLI use:**

```bash
# Stdio transport (default) — for Claude Desktop / Cursor
bridgemcp-filesystem --root /workspace

# Read-only with a size limit
bridgemcp-filesystem --root /data --read-only --max-file-size-mb 5

# HTTP/SSE transport
bridgemcp-filesystem --root /app --http --port 8080
```

**Claude Desktop config (`claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "bridgemcp-filesystem",
      "args": ["--root", "/workspace"]
    }
  }
}
```

## Tools

| Tool | Description |
|---|---|
| `read_file` | Read file content. Returns `is_binary=true, content=null` for binary files. |
| `write_file` | Write text to a file. Optionally creates missing parent directories. |
| `list_directory` | List directory contents with type, size, and timestamps. |
| `search_files` | Glob search within a directory, optionally recursive. |
| `get_info` | Metadata for a file or directory: type, size, timestamps, permissions. |
| `create_directory` | Create a directory, optionally including parents. |
| `copy_path` | Copy a file or directory tree. |
| `move_path` | Move a file or directory. Supports cross-filesystem moves. |
| `rename_path` | Atomic rename within the same filesystem. |
| `delete_path` | Delete a file or directory. **Requires `confirm=True`.** |

## Safety model

### Root confinement

Set `root` to restrict all operations to a single directory tree:

```python
app = create_app(root="/workspace")
```

Any path that resolves outside `/workspace` — including `../../etc/passwd` and symlinks pointing out — raises an error **before** any IO occurs. The check uses `Path.resolve()` which follows all symlinks, so there is no way to escape the root through link indirection.

When `root` is not set, the server operates in **unrestricted mode**: any path on the filesystem is accessible. This is appropriate for trusted local tools but should not be used in multi-user or production environments.

### Read-only mode

```python
app = create_app(root="/data", read_only=True)
```

All mutating tools (`write_file`, `create_directory`, `copy_path`, `move_path`, `rename_path`, `delete_path`) raise an error immediately without touching the filesystem.

### Delete safeguard

`delete_path` always requires `confirm=True`:

```python
# This always raises an error:
app.call("delete_path", path="/workspace/file.txt")

# This proceeds with deletion:
app.call("delete_path", path="/workspace/file.txt", confirm=True)
```

The configured root directory can never be deleted, even with `confirm=True`.

## Development

```bash
git clone https://github.com/Arsie-codes/bridgemcp-server-filesystem
cd bridgemcp-server-filesystem
pip install -e '.[dev]'

ruff check bridgemcp_filesystem tests
black --check bridgemcp_filesystem tests
pyright bridgemcp_filesystem
pytest tests/ -v
```

## License

MIT — see [LICENSE](LICENSE).

## Links

- [BridgeMCP framework](https://github.com/Arsie-codes/bridgemcp)
- [PyPI](https://pypi.org/project/bridgemcp-server-filesystem/)
- [Discussions](https://github.com/Arsie-codes/bridgemcp-server-filesystem/discussions)
- [Issues](https://github.com/Arsie-codes/bridgemcp-server-filesystem/issues)