The problem

Your AI can write the code, but it can't see your project. You copy files into the chat, paste test output back, and run every command yourself. Giving it a raw terminal solves that, but then it can touch everything.

Local Commander sits in between. Your AI gets real tools for real work on your machine, inside the folders you pick, with commands you allow. You keep working in the chat you already have open.

What people use it for

Try asking:

"Run the tests in my-app and tell me what fails."
"Start the dev server and check that port 3000 answers."
"Show me what changed in the repo since yesterday."

Why Local Commander

🔒 You choose the access. Your AI sees only the folders you pick. Secret files such as .env and private keys are blocked by default.

🧰 Real tools, not a raw shell. Commands run from an allowlist (Git, Node, npm, Python and similar) with separate arguments. There is no free-form shell string to inject into.

⚡ Parallel work without collisions. Independent commands run side by side. Long-running processes such as dev servers keep running while your AI checks their output.

🏠 Stays on your machine. The server runs locally and talks only to the AI client that started it. No account, no telemetry, and the audit log is off unless you turn it on.

🔌 Works with the AI you already have. Claude Desktop, Claude Code, Cursor, Codex, ChatGPT over a tunnel, or anything that speaks MCP.

Get started

Pick the way that fits you. Each takes a couple of minutes.

Before you install

Technical reference

• Tools
• Install options: setup · npx · Docker · Node.js · HTTP and ChatGPT
• Security model
• Configuration
• Development

Tools

Install options

One-command setup

Requirements: Node.js 20+.

npx -y local-commander-mcp-agent setup --root /path/to/your/projects --client all

This adds a local-commander entry to the Claude Desktop and/or Cursor MCP configuration, keeping a timestamped backup of the previous file. Repeat --root for more folders, use --client claude-desktop or --client cursor for one client, --dry-run to preview, and setup --remove to take the entry out again. Restart the client afterwards.

npx

Requirements: Node.js 20+. Folders the server may access follow --stdio:

{
  "mcpServers": {
    "local-commander": {
      "command": "npx",
      "args": ["-y", "local-commander-mcp-agent", "--stdio", "/path/to/your/projects"]
    }
  }
}

On Windows some clients need "command": "cmd" with "args": ["/c", "npx", "-y", ...]; setup writes that form for you.

LCMCP_ROOTS still works instead of folder arguments. In stdio mode local state is kept in ~/.local-commander-mcp-agent unless LCMCP_OAUTH_STATE_PATH is set.

On Windows use ; between several roots and paths such as C:\\Users\\you\\source\\repos. The package includes the small Windows file-read helper, so nothing is compiled at install time.

Docker

The container is the sandbox: the server only sees the folders you mount under /workspace. The image is published as ghcr.io/netbka/local-commander-mcp-agent (tags latest and each version). To build it yourself: docker build -t local-commander-mcp-agent .

MCP client configuration (Claude Desktop, Cursor, Claude Code, Codex and others):

{
  "mcpServers": {
    "local-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/projects:/workspace/projects",
        "ghcr.io/netbka/local-commander-mcp-agent"
      ]
    }
  }
}

On Windows use a path such as C:\\Users\\you\\source\\repos:/workspace/repos. The image contains Node.js 22, Git and Python 3. Add tools by extending the image.

HTTP instead of stdio:

docker run --rm -p 127.0.0.1:17321:17321 \
  -e LCMCP_TOKEN=generate-a-long-random-token \
  -v /path/to/your/projects:/workspace/projects \
  ghcr.io/netbka/local-commander-mcp-agent --http

The image defaults to --stdio; any other argument after the image name (here --http) replaces it and starts the HTTP server. The endpoint is http://127.0.0.1:17321/mcp with Authorization: Bearer <token>. Publish the port on 127.0.0.1 only.

Node.js

Requirements: Node.js 20+.

npm install
npm run build

{
  "mcpServers": {
    "local-commander": {
      "command": "node",
      "args": ["/path/to/local-commander-mcp-agent/dist/index.js", "--stdio", "/path/to/your/projects"]
    }
  }
}

In stdio mode stdout carries only MCP messages and logs go to stderr. HTTP authentication settings do not apply, because only the client that started the process can talk to it.

On Windows the build also compiles a small file-read helper (release/personal/OwnerBridge.exe) with the .NET Framework compiler that ships with Windows. Other platforms use the Node reader.

HTTP and ChatGPT

cp local-commander.config.example.json local-commander.config.json   # set "roots"
LCMCP_AUTH_MODE=oauth LCMCP_PUBLIC_BASE_URL=https://your-tunnel.example.com npm start

When the client starts authorization, a one-time approval code is printed in the local terminal. Bearer mode (LCMCP_AUTH_MODE=bearer, LCMCP_TOKEN=...) is available for local clients.

Security model

• Direct file operations are constrained to the configured roots; existing paths are resolved with realpath, so symlinks cannot escape a root.
• Common secret files (.env, private keys, credential files) are blocked by default.
• command_run takes an executable and an argument array, never a shell string. Executables are allowlisted and resolved from absolute PATH directories only.
• Command time and output are capped; HTTP is limited to localhost and redirects are not followed.
• Child processes are not OS-sandboxed outside Docker: an allowed interpreter can read anything the account can read. For hard containment use the Docker image, a separate low-privilege account or a VM.

Configuration

The config file can also set the command allowlist (shell.allowedCommands), size limits and localhost hosts; see local-commander.config.example.json.

Development

npm run typecheck
npm test
npm run build