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",
        "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
      }
    }
  }
}

Restart Claude Desktop after saving.

[!TIP] Set require_session_id: false to prevent approval loops in Claude Desktop.

---

How It Works

Commands go through a validation pipeline before execution:

1. Pattern matching — blocks dangerous constructs (system(), shell escapes, etc.)
2. Command classification — each command must be in the read, write, system, or blocked list
3. Directory check — target directory must be whitelisted or session-approved
4. Approval check — write/system commands require session approval

Pipes, semicolons, and & are supported — each segment is validated independently.

What's Allowed

Category	Commands	Approval
Read	ls, cat, grep, find, head, tail, sort, wc, …	Auto
Write	cp, mv, rm, mkdir, touch, chmod, awk, sed, …	Required
System	ps, ping, curl, ssh, xargs, …	Required
Blocked	sudo, bash, sh, python, eval, …	Always denied

What's Blocked

Shells, scripting interpreters, and known command-execution vectors are blocked — including indirect execution through awk system(), sed /e, find -exec, tar --checkpoint-action, env, and xargs. See docs/SECURITY.md for the full list.

---

Configuration

The server works out of the box with sensible defaults. Customize via JSON config, environment variables, or .env files:

# Whitelist directories
export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"

# Add commands (merges with defaults)
export CMD_LINE_MCP_COMMANDS_READ="jq,rg"

See docs/CONFIGURATION.md for full configuration reference, MCP tool documentation, and directory security details.

---

License

MIT