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.

Tools

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