bridgemcp-server-filesystem

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

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.

Links

• BridgeMCP framework
• PyPI
• Discussions
• Issues