Skip to main content
Glama
Command-Line MCP Server

Command-Line MCP Server

by andresthor

Command-Line MCP Server

PyPI version Python Versions License: MIT

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

Related MCP server: Terminal MCP Server

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"
      }
    }
  }
}

Restart Claude Desktop after saving.

WARNING

require_session_id: false is the default and prevents approval loops in Claude Desktop, but it auto-approves write and system commands; set allow_user_confirmation: false to require explicit approval instead. The model can request that approval itself through approve_command_type, so your client's tool confirmation is the real gate. auto_approve_directories_in_desktop_mode: true turns off directory confinement entirely. See docs/SECURITY.md.


How It Works

Commands go through a validation pipeline before execution:

  1. Pattern matching — rejects configured dangerous patterns (writes to system paths, tar --to-command, etc.)

  2. Parsing — the command is parsed by a strict lexer; unsupported shell syntax is rejected

  3. Command classification — each command must be in the read, write or system list, and not blocked

  4. Path check — every path, glob match and redirect target in every command must be whitelisted or session-approved

  5. Approval check — write/system commands require approval

Pipes, ;, && and || are supported, and each command is validated independently. Background &, variables ($NAME), command substitution and subshells are rejected. The server runs its own fully quoted rendering of the validated command, never the raw input.

What's Allowed

Category

Commands

Approval

Read

ls, cat, grep, head, tail, wc, du, …

Auto

Write

cp, mv, rm, mkdir, touch, chmod, gzip, echo, …

Required

System

ps, ping, netstat, who, …

Required

Blocked

sudo, bash, sh, python, eval, env, xargs, …

Always denied

What's Blocked

  • Hard-blocked floor — shells, interpreters and programs that run other programs (env, xargs, nohup, timeout, …). Enforced in code, so a config cannot re-enable them.

  • Blocked list — adds dd, mkfs, mount, shutdown and similar; configurable.

  • Dangerous patterns — configurable regexes, by default covering writes to system paths, rm -rf /, tar command execution and find -exec with sh, bash, zsh, ksh, csh, fish, python/python2/python3, perl, ruby, node or env. Commands whose options can write files or run other programs (find, sort, tar, zip, unzip, curl, wget) are left out of the defaults until per-command argument rules exist; adding them to your config re-enables those options.

See docs/SECURITY.md for the full lists, the threat model and known limitations.


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

Available Tools

8 tools
approve_command_typeB

Approve a command type for the current session.

Args: command_type: The command type to approve (read, write, system) session_id: The session ID remember: Whether to remember this approval for the session

Returns: A dictionary with approval status

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

approve_directoryC

Approve access to a directory for the current session.

Args: directory: The directory to approve access to session_id: The session ID remember: Whether to remember this approval for the session

Returns: A dictionary with approval status

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

execute_commandC

Execute a Unix/macOS terminal command.

Args: command: The command to execute session_id: Optional session ID for permission management

Returns: A dictionary with command output and status

Inputs: command (required), session_id. Returns: object

execute_read_commandB

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

Args: command: The read-only command to execute session_id: Optional session ID for permission management

Returns: A dictionary with command output and status

Inputs: command (required), session_id. Returns: object

get_command_helpB

Get detailed help about command capabilities and usage.

This tool provides comprehensive information about:

  • Supported commands in each category (read, write, system)

  • Blocked commands for security reasons

  • Command chaining capabilities (|, ;, && and ||)

  • Usage restrictions and examples

Returns: A dictionary with detailed information about command capabilities and usage

Inputs: no named parameters. Returns: object

get_configurationB

Get the current configuration settings.

Returns: The current configuration settings

Inputs: no named parameters. Returns: object

list_available_commandsB

List all available commands by category.

Returns: A dictionary with commands grouped by category

Inputs: no named parameters. Returns: object

list_directoriesB

List all whitelisted and approved directories.

Args: session_id: Optional session ID to get session-specific approvals

Returns: A dictionary with globally whitelisted and session-approved directories

Inputs: session_id. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools have mostly distinct purposes: execute_command and execute_read_command overlap in executing commands, but the read-only distinction is meaningful for permission safety. Approval tools are clearly differentiated by type vs directory. Help and listing tools are distinct. No major confusion.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (get_, approve_, execute_, list_). No mixing of conventions.

    Tool Count5/5

    8 tools is well-scoped for a command-line execution server with permission management. Each tool serves a clear purpose.

    Completeness4/5

    Core functionality (execute, approve, list, get help/config) is covered. However, there is no tool to revoke approvals or reset session permissions, which could be a minor gap for full lifecycle management.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to securely execute shell commands on local machines through an SSH interface with session management, command execution, and sudo support.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables safe execution of terminal commands across different shells (bash, cmd, PowerShell) with configurable timeouts, working directories, and resource limits for command-line operations through AI assistants.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to securely execute remote SSH commands, perform file transfers, and monitor system status through a standardized interface. It features robust security controls including command whitelisting, blacklisting, and credential isolation to prevent unauthorized operations.
      10
      23 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to execute terminal commands on a host machine with configurable, granular permission controls and safety protections. It features multiple security modes, including allowlists and manual approval, to ensure safe command execution within specified directories.
      6
      Apache 2.0