Command-Line MCP Server

An MCP server that lets AI assistants run terminal commands safely. Commands are categorized (read/write/system), directories are whitelisted, and dangerous patterns are blocked automatically.

---

Quick Start

pip install cmd-line-mcp

# Or from source
git clone https://github.com/andresthor/cmd-line-mcp.git
cd cmd-line-mcp
pip install -e .

Run the server:

cmd-line-mcp                        # default config
cmd-line-mcp --config config.json   # custom config

---

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cmd-line": {
      "command": "/path/to/venv/bin/cmd-line-mcp",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false"
      }
    }
  }
}

Restart Claude Desktop after saving.

[!WARNING] require_session_id: false is the default and prevents approval loops in Claude Desktop, but it auto-approves write and system commands; set allow_user_confirmation: false to require explicit approval instead. The model can request that approval itself through approve_command_type, so your client’s tool confirmation is the real gate. auto_approve_directories_in_desktop_mode: true turns off directory confinement entirely. See docs/SECURITY.md.

---

How It Works

Commands go through a validation pipeline before execution:

1. Pattern matching — rejects configured dangerous patterns (writes to system paths, tar --to-command, etc.)
2. Parsing — the command is parsed by a strict lexer; unsupported shell syntax is rejected
3. Command classification — each command must be in the read, write or system list, and not blocked
4. Path check — every path, glob match and redirect target in every command must be whitelisted or session-approved
5. Approval check — write/system commands require approval

Pipes, ;, && and || are supported, and each command is validated independently. Background &, variables ($NAME), command substitution and subshells are rejected. The server runs its own fully quoted rendering of the validated command, never the raw input.

What’s Allowed