cmd-line-mcp

A secure Model Context Protocol (MCP) server that allows AI assistants to execute terminal commands with controlled directory access and command permissions.

Written in JavaScript (ESM) — works with npx out of the box, no Python runtime required.

Quick Start

Run with npx (no install)

npx cmd-line-mcp
npx cmd-line-mcp --config /path/to/config.json
npx cmd-line-mcp --config config.json --env .env

Global install

npm install -g cmd-line-mcp
cmd-line-mcp

Local install

npm install cmd-line-mcp
npx cmd-line-mcp

Claude Desktop Integration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cmd-line": {
      "command": "npx",
      "args": ["-y", "cmd-line-mcp"],
      "env": {
        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
        "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
      }
    }
  }
}

Or with a custom config file:

{
  "mcpServers": {
    "cmd-line": {
      "command": "npx",
      "args": ["-y", "cmd-line-mcp", "--config", "/path/to/config.json"]
    }
  }
}

Restart Claude for Desktop after saving.

Configuration

Configuration is resolved in this order (later overrides earlier):

1. Built-in default_config.json
2. File pointed to by CMD_LINE_MCP_CONFIG environment variable
3. --config <path> CLI argument
4. .env file (searched from cwd upward)
5. CMD_LINE_MCP_* environment variables

Example config.json

{
  "security": {
    "whitelisted_directories": ["/home", "/tmp", "~/Projects"],
    "auto_approve_directories_in_desktop_mode": false,
    "require_session_id": false,
    "allow_command_separators": true
  },
  "commands": {
    "read": ["ls", "cat", "grep"],
    "write": ["touch", "mkdir", "rm"],
    "system": ["ps", "ping"]
  }
}

Environment Variable Format

CMD_LINE_MCP_<SECTION>_<SETTING>

Examples:

export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"
export CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE=true
export CMD_LINE_MCP_COMMANDS_READ="awk,jq,wc"

Available MCP Tools

Supported Commands (default)

Read (no approval needed)

ls, pwd, cat, less, head, tail, grep, find, which, du, df, file, uname, hostname, uptime, date, whoami, id, env, history, sort, wc, ...

Write (approval required)

cp, mv, rm, mkdir, rmdir, touch, chmod, chown, ln, echo, tar, gzip, zip, unzip, awk, sed, ...

System (approval required)

ps, top, htop, who, netstat, ifconfig, ping, ssh, curl, wget, xargs, ...

Blocked (always denied)

sudo, su, bash, sh, zsh, eval, exec, dd, mkfs, shutdown, reboot, ...

Security Architecture

┌───────────────────────────────────────────────────────────────┐
│                   COMMAND-LINE MCP SERVER                     │
├──────────────────┬────────────────────────┬───────────────────┤
│ COMMAND SECURITY │   DIRECTORY SECURITY   │ SESSION SECURITY  │
├──────────────────┼────────────────────────┼───────────────────┤
│ ✓ Read commands  │ ✓ Directory whitelist  │ ✓ Session IDs     │
│ ✓ Write commands │ ✓ Runtime approvals    │ ✓ Persistent      │
│ ✓ System commands│ ✓ Path validation      │   permissions     │
│ ✓ Blocked list   │ ✓ Home dir expansion   │ ✓ Auto timeouts   │
│ ✓ Pattern filters│ ✓ Subdirectory check   │ ✓ Desktop mode    │
└──────────────────┴────────────────────────┴───────────────────┘

Requirements

• Node.js >= 18
• macOS or Linux

License

MIT

Original Python source

The original Python implementation is preserved in the temp/ directory for reference.