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

Tool	Description
execute_command	Execute any allowed command (read/write/system)
execute_read_command	Execute read-only commands only
approve_directory	Grant access to a directory for a session
approve_command_type	Grant permission for a command category
list_directories	List whitelisted and approved directories
list_available_commands	Show commands grouped by category
get_command_help	Get usage guidance and examples
get_configuration	View current server configuration

---

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.