bridgemcp-server-filesystem

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

License: MIT

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

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

Quick start

Programmatic use:

from bridgemcp_filesystem import create_app

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

CLI use:

# 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):

{
  "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:

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

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:

# 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

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.

bridgemcp-server-filesystem