cli-bridge

A local Model Context Protocol (MCP) server that gives Claude Desktop — or any MCP-compatible client — sandboxed filesystem access and gated shell command execution, scoped entirely to a single workspace root directory.

What is this?

cli-bridge is a lightweight MCP server that plugs into Claude Desktop (or any MCP client) and gives it:

• 📂 Filesystem tools — read, write, edit, search, and grep files, all confined to one workspace root
• 💻 Shell execution — run real commands on your machine, gated behind an explicit Dev Mode toggle
• 📝 Project memory — an append-only journal (PROJECT_LOG.md) so an agent can pick up context across sessions
• 🔒 Audit logging — every tool call recorded to a local log file, nothing sent anywhere else

Everything runs locally, on your machine — no external API calls, no cloud dependency, no telemetry.

⚠️ Dev Mode — Read Before Enabling Shell Execution

[!CAUTION] execute_command can run any executable available on your system, with the same permissions as the app hosting the MCP client. This is real shell execution, not a sandbox.

Everything else — reading, searching, editing files in the workspace — works fully with Dev Mode left off. If you're unsure, leave it off.

Features

Security Architecture

┌─────────────────────────────────────────────┐
│              MCP Client (Claude)             │
└────────────────────┬──────────────────────────┘
                      │ tool calls
┌────────────────────▼──────────────────────────┐
│                  cli-bridge                    │
│  ┌───────────────────────────────────────────┐ │
│  │ 1. Path Confinement (resolveSafePath)      │ │
│  │ 2. Symlink Resolution (fs.realpathSync)    │ │
│  │ 3. Dev Mode Gate (execute_command only)    │ │
│  │ 4. Shell Metacharacter Scan (Windows only) │ │
│  │ 5. Audit Log Write (.cli-bridge-audit.log) │ │
│  └───────────────────────────────────────────┘ │
└────────────────────┬──────────────────────────┘
                      │ confined to
              <workspaceRoot>/

• Path Confinement — every path (including command cwd) resolves strictly relative to the workspace root; traversal attempts are rejected.
• Symlink Protection — symlinks pointing outside the workspace boundary are resolved and blocked.
• Dev Mode Gating — execute_command is hard-blocked at the handler entry point until explicitly toggled on.
• No Command Allowlist — once Dev Mode is on, any executable on the host can run. See the warning above.
• Shell Metacharacter Scanning — Windows build-tool wrappers (npm, npx, yarn, pnpm, tsc, jest, eslint, prettier) run with shell: true; arguments are scanned for & | ; $ > < ^ and blocked if found. Everything else runs with shell: false.
• Audit Logging — every tool call is recorded as JSON in <workspaceRoot>/.cli-bridge-audit.log (timestamp, arguments truncated to 200 chars, status: success / error / blocked).

Compatibility

Windows-specific handling (the .cmd/.bat wrapper allowlist and shell-metacharacter scan) only applies when process.platform === 'win32'. On macOS/Linux, all commands spawn directly with shell: false. If you run this on macOS or Linux, feedback/issues are welcome.

Token-Efficient Workflows

1. Use grep_content to locate keywords/functions before reading full files.
2. Use read_file with start_line/end_line once you have coordinates.
3. Use edit_file for targeted changes instead of rewriting whole files.
4. Use git diff / git log / git show via execute_command (Dev Mode required) to verify changes on disk.

Project Journal

An append-only development log at <workspaceRoot>/PROJECT_LOG.md, meant to be read by an agent at the start of a new session to recover prior context. Agents call log_journal_entry after completing work, including file lists and commit hashes.

Installation

Prerequisites: Node.js v18.17.0+ (v20 or v24 LTS recommended)

npm install
npm run build

Configuration in Claude Desktop

Finding your config file (Windows)

Depending on how Claude Desktop was installed (standard installer vs. MSIX/Microsoft Store package), its configuration file location differs. You can run this PowerShell command to locate your claude_desktop_config.json automatically:

Get-ChildItem -Path "$env:APPDATA\Claude\claude_desktop_config.json", "$env:LOCALAPPDATA\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json" -ErrorAction SilentlyContinue | Select-Object FullName

[!NOTE] If neither path returns a result, the configuration file has likely not been created yet (which happens after opening Claude Desktop for the first time) or is installed in a non-standard location.

Manual File Paths Reference

• Windows: %APPDATA%\Claude\claude_desktop_config.json (or %LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude\claude_desktop_config.json for Store/MSIX installs)
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Registering cli-bridge

Add cli-bridge to the mcpServers object inside your claude_desktop_config.json:

{
  "mcpServers": {
    "cli-bridge": {
      "command": "node",
      "args": [
        "<YOUR_DEFAULT_INSTALLATION_PATH>/build/index.js",
        "<YOUR_DEFAULT_WORKSPACE_PATH>"
      ],
      "env": {
        "WORKSPACE_ROOT": "<YOUR_DEFAULT_WORKSPACE_PATH>"
      }
    }
  }
}

• Replace <YOUR_DEFAULT_INSTALLATION_PATH> with the folder where you cloned cli-bridge (e.g. C:/Projects/cli-bridge on Windows or /Users/username/Projects/cli-bridge on macOS/Linux).
• Replace <YOUR_DEFAULT_WORKSPACE_PATH> with the target project workspace folder you want cli-bridge to manage.

Testing and Debugging

npx @modelcontextprotocol/inspector node build/index.js <YOUR_DEFAULT_WORKSPACE_PATH>

_{Built as a local-first MCP tool. No cloud dependency, no telemetry, no data leaves your machine.}