File Bridge

A small local MCP server that lets an AI assistant (Claude Desktop, Cursor, VS Code) read and search the files in one folder you choose. It is read-only unless you switch writing on, and it makes no network connections of its own.

What it does not do: when your AI assistant reads a file through the bridge, the assistant sends that text to its own provider (Anthropic, OpenAI, …) under that provider's terms. File Bridge controls which files the assistant can reach; it does not hide their contents from the assistant.

Need client details kept away from the AI? Airgap Private Desk is our Windows app built on this bridge: it replaces names, addresses and account numbers with placeholders before the AI sees a document, and fills them back in on your PC when the AI saves a draft.

Build status: UNSIGNED INTERNAL (no Authenticode certificate yet). See proof-pack/SIGNING.md.

Client / COLP install guide (plain English): CLIENT-README.md.

Quick start (Windows - recommended)

One-command installer (setup may use the internet once; the running bridge makes no network connections):

powershell -ExecutionPolicy Bypass -File .\installer\Install-FileBridge.ps1 -RootPath "C:\Path\To\Your\Files"

Add -AllowWrites if the AI should be able to create and edit files. Without it the bridge is read-only.

Post-install smoke test:

powershell -ExecutionPolicy Bypass -File .\scripts\self_test.ps1 -RootPath "C:\Path\To\Your\Files"

Details: installer/README.md. Zero-egress proof: proof-pack/.

Uninstall (also removes the connector entries it added to Claude Desktop and Cursor):

powershell -ExecutionPolicy Bypass -File .\installer\Uninstall-FileBridge.ps1

Advanced / developer install

pip install airgap-file-bridge
FILE_BRIDGE_ROOT_PATH=/path/to/files airgap-file-bridge --check

--check confirms the configuration and exits. --version prints the version.

MCP client config (Claude Desktop, Cursor, VS Code)

Prefer the Windows installer when possible (it writes a local launcher for you). Manual example for Windows, using the full path to the executable:

{
  "mcpServers": {
    "file-bridge": {
      "command": "C:\\Path\\To\\venv\\Scripts\\airgap-file-bridge.exe",
      "env": {
        "FILE_BRIDGE_ROOT_PATH": "C:/Path/To/Files",
        "FILE_BRIDGE_READ_ONLY": "true"
      }
    }
  }
}

macOS / Linux, if the command is on PATH:

{
  "mcpServers": {
    "file-bridge": {
      "command": "airgap-file-bridge",
      "env": { "FILE_BRIDGE_ROOT_PATH": "/path/to/files" }
    }
  }
}

Configuration

Environment prefix: FILE_BRIDGE_*. Legacy FILESYSTEM_MCP_* names still work when the matching FILE_BRIDGE_* value is unset.

Environment variable	Default	Description
FILE_BRIDGE_ROOT_PATH	(required)	The one folder the AI may use. The bridge will not start without it, and refuses a whole drive or your entire user folder.
FILE_BRIDGE_READ_ONLY	true	Set to false to allow write_file and patch_file.
FILE_BRIDGE_BACKUP_ON_WRITE	true	Keep the previous version of a changed file in .file-bridge/versions.
FILE_BRIDGE_MAX_FILE_SIZE	10 MB	Max file size for operations. A tool call can lower it, never raise it.
FILE_BRIDGE_FOLLOW_SYMLINKS	false	Allow paths through symlinks. Links can never lead outside the folder either way.
FILE_BRIDGE_ALLOW_ABSOLUTE_PATHS	false	Accept absolute paths (they must still be inside the folder).
FILE_BRIDGE_DEFAULT_ENCODING	utf-8	Text encoding. Files saved in older Windows encodings are read automatically.
FILE_BRIDGE_ALLOW_BROAD_ROOT	false	Allow a drive root or home folder as the root (not advised).
FILE_BRIDGE_LOG_LEVEL	INFO	DEBUG, INFO, WARNING or ERROR. Logs go to stderr.

Tools

Tool	Description
read_file	Read a text file (any language, including older Windows encodings). Binary files come back base64-encoded.
list_dir	List a folder, optionally recursively, with a name filter and a depth limit.
search_files	Search file contents with ripgrep: regex or plain text, context lines, file filters.
glob	Find files by pattern, e.g. **/*.md. Patterns cannot contain ...
write_file	Write a file atomically. Read-only mode refuses it.
patch_file	Replace exact text. Must match exactly once unless you say otherwise. Keeps encoding and line endings. Read-only mode refuses it.

Safety behaviour

• Every path is resolved and must stay inside the folder. Folder links (symlinks and NTFS junctions) that lead elsewhere are not listed, searched or read.
• Search terms are always passed to ripgrep as patterns, never as options, and ripgrep cannot read the MCP channel.
• Writes are atomic, and the previous version is kept in .file-bridge/versions, which the AI cannot change.
• The bridge talks over stdio only. It opens no ports and makes no network calls.

Development

pip install -e ".[dev]"
pytest -v
ruff check src/ tests/
mypy --config-file mypy.ini --strict src/filesystem_mcp

Search tests need ripgrep (rg) on PATH.

License

MIT