Skip to main content
Glama
Sign In
cmd-line-mcp

cmd-line-mcp

by wwqdrh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

cmd-line-mcp

npm version License: MIT Node.js

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.

Available Tools

8 tools
approve_command_typeC

Approve a command type for the current session.

Inputs: command_type (required), session_id (required), remember.

approve_directoryC

Approve access to a directory for the current session.

Inputs: directory (required), session_id (required), remember.

execute_commandC

Execute a Unix/macOS terminal command.

Inputs: command (required), session_id.

execute_read_commandA

Execute a read-only Unix/macOS terminal command (ls, cat, grep, etc.).

Inputs: command (required), session_id.

get_command_helpB

Get detailed help about command capabilities and usage.

Inputs: no named parameters.

get_configurationC

Get the current configuration settings.

Inputs: no named parameters.

list_available_commandsB

List all available commands by category.

Inputs: no named parameters.

list_directoriesC

List all whitelisted and approved directories.

Inputs: session_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some potential overlap between 'execute_command' and 'execute_read_command' as both execute commands, which could cause confusion about when to use each. The other tools are clearly differentiated by their specific functions like approval, listing, and configuration.

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern throughout, such as 'approve_command_type', 'execute_command', and 'list_directories'. However, there is a minor deviation with 'get_command_help' and 'get_configuration' using 'get' instead of a more action-oriented verb, but overall the pattern is predictable and readable.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a command-line MCP server, covering key operations like execution, approval, listing, and configuration without being overwhelming. Each tool appears to serve a necessary function in managing and executing commands.

    Completeness4/5

    The toolset provides good coverage for command-line operations, including execution, approval, listing, and help. A minor gap is the lack of tools for updating or deleting configurations or approvals, but agents can likely work around this with the existing tools for most workflows.

    Resources

    Related MCP Connectors