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

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