cli-bridge MCP server
Commit Nov 1, 2026Provides sandboxed filesystem access and gated shell command execution scoped to a single workspace root for MCP-compatible clients.
Also known as anshupriyan/cli-bridge
- Stars
- 15
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- MIT
What is cli-bridge MCP?
cli-bridge provides sandboxed filesystem access and gated shell command execution scoped to a single workspace root for MCP-compatible clients.
Summary generated from the project's README
About cli-bridge MCP server
Giving AI agents controlled access to your local files and terminal is what cli-bridge enables for developers using Claude Desktop or other MCP-compatible clients. This local server operates within a single workspace root, ensuring that all filesystem operations and shell commands remain confined to a specific directory. It provides a suite of tools for reading, writing, searching, and editing files, alongside a gated mechanism for executing system commands.
To maintain security, shell execution is disabled by default and requires an explicit toggle via the toggle_dev_mode tool to activate. The server includes a project journal using a PROJECT_LOG.md file, which allows an agent to maintain context and memory across different sessions. Every action is recorded in a local audit log for transparency. Because it runs entirely on your machine without external API calls or telemetry, your data stays private and under your direct control.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
WORKSPACE_ROOT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableanshupriyan/cli-bridge is public and reachablegithub.com/anshupriyan/cli-bridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/anshupriyan/cli-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcli-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_commandcan 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
| 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.
| 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
<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_commandis 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 withshell: true; arguments are scanned for& | ; $ > < ^and blocked if found. Everything else runs withshell: 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
| 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
- Use
grep_contentto locate keywords/functions before reading full files. - Use
read_filewithstart_line/end_lineonce you have coordinates. - Use
edit_filefor targeted changes instead of rewriting whole files. - Use
git diff/git log/git showviaexecute_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.jsonfor Store/MSIX installs) - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Registering cli-bridge
Claude Desktop
Add cli-bridge to the mcpServers object inside your claude_desktop_config.json:
{
"mcpServers": {
"cli-bridge": {
"command": "node",
"args": [
"<PATH_TO_CLI_BRIDGE>/build/index.js",
"<PATH_TO_YOUR_WORKSPACE>"
],
"env": {
"WORKSPACE_ROOT": "<PATH_TO_YOUR_WORKSPACE>"
}
}
}
}
Qwen Studio
Add cli-bridge to the mcpServers object in your Qwen Studio configuration:
{
"mcpServers": {
"cli-bridge": {
"command": "npx",
"args": [
"node",
"<PATH_TO_CLI_BRIDGE>/build/index.js",
"<PATH_TO_YOUR_WORKSPACE>"
],
"env": {
"WORKSPACE_ROOT": "<PATH_TO_YOUR_WORKSPACE>"
}
}
}
}
[!IMPORTANT] Windows Path Formatting in JSON: Because
claude_desktop_config.jsonis a standard JSON file, single backslashes copied directly from File Explorer's address bar (e.g.C:\Projects\cli-bridge) will cause JSON parsing errors unless escaped.You have two valid options for Windows paths:
- Double Backslashes:
"C:\\Projects\\cli-bridge\\build\\index.js"- Forward Slashes (Recommended):
"C:/Projects/cli-bridge/build/index.js"(works natively in Node.js on Windows and is easier to type)
Format Example Path Status ❌ Single Backslash "C:\Projects\cli-bridge"Fails JSON Parsing ✅ Double Backslash "C:\\Projects\\cli-bridge"Valid JSON ✅ Forward Slash "C:/Projects/cli-bridge"Valid & Recommended
- Replace
<PATH_TO_CLI_BRIDGE>with the folder where you clonedcli-bridge. - Replace
<PATH_TO_YOUR_WORKSPACE>with the target project workspace folder you wantcli-bridgeto manage.
Testing and Debugging
npx @modelcontextprotocol/inspector node build/index.js <YOUR_DEFAULT_WORKSPACE_PATH>
cli-bridge MCP questions
Does this server send my data to the cloud?
No, the server runs entirely locally on your machine with no external API calls, cloud dependency, or telemetry.
How can I track what the AI agent has done in previous sessions?
The server uses an append-only journal called PROJECT_LOG.md that allows an agent to recover context across sessions.