Cli Bridge

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.

| | | |---|---| | Default state | Dev Mode is OFF every time the server starts. execute_command is blocked before anything spawns. | | Turning it on | Requires an explicit toggle_dev_mode({ enable_dev_mode: true }) call — nothing enables it silently. | | Your responsibility | Once enabled, any command run — including destructive ones (deleting files, modifying system state, installing software, network calls) — executes for real. There is no command allowlist, no confirmation beyond your MCP client's own approval settings, and no undo. | | Liability | This project's author/developer is not responsible for data loss, system damage, security incidents, or any other consequence of enabling Dev Mode or using execute_command. Enabling it is a decision you make, at your own risk. |

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

---

Features

🔍 Read-Only Tools (click to expand)

| Tool | Description | |---|---| | read_file(path, start_line?, end_line?) | Reads UTF-8 file contents, optional line-range support | | list_directory(path, recursive?) | Lists directory contents (names, sizes, dir flags) | | search_files(pattern, path?) | Recursive glob search (e.g. *.ts, **/*.js) | | grep_content(pattern, path?, case_sensitive?, max_results?) | Fast fixed-string search via bundled @vscode/ripgrep, capped at max_results (default 50) | | get_dev_mode_status() | Reports whether shell execution is ENABLED or BLOCKED | | get_recent_journal_entries(count?, project?) | Reads the last N entries from PROJECT_LOG.md |

All tools are strictly confined to the workspace root directory.

✍️ Write & Execution Tools (click to expand)

| Tool | Description | |---|---| | write_file(path, content) | Overwrites/creates a file, auto-creates parent directories | | edit_file(path, old_str, new_str) | Targeted find-and-replace; errors on zero or multiple matches | | execute_command(command, args, cwd?, timeout?) | Shell execution, gated by Dev Mode — see warning above | | toggle_dev_mode(enable_dev_mode) | Enables/re-locks shell execution for the current session only | | log_journal_entry(summary, files_changed?, commit_hash?, project?) | Appends a structured entry to PROJECT_LOG.md |

---

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
              /

• 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 & | ; $ > /.cli-bridge-audit.log (timestamp, arguments truncated to 200 chars, status: success / error / blocked).

---

Compatibility

| Platform | Status | |---|---| | 🪟 Windows 11 (x64) | ✅ Tested and verified | | 🍎 macOS (arm64 / x64) | ⚠️ Architecturally supported (pure ESM + auto-resolved ripgrep binary), not yet live-tested | | 🐧 Linux (x64) | ⚠️ Architecturally supported, not yet live-tested |

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 /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": [
        "/build/index.js",
        ""
      ],
      "env": {
        "WORKSPACE_ROOT": ""
      }
    }
  }
}

• Replace ` 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 ` with the target project workspace folder you want cli-bridge` to manage.

---

Testing and Debugging

npx @modelcontextprotocol/inspector node build/index.js 

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anshupriyan
• Source: anshupriyan/cli-bridge
• License: MIT

Install and usage instructions live in the source repository linked above.