Skip to main content

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

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.


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

Metadata

Release files for cmd-line-mcp 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cmd-line-mcp 0.6.1
File Size Uploaded Provenance Actions
cmd_line_mcp-0.6.1.tar.gz 67.8 kB Without provenance Details for cmd_line_mcp-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cmd-line-mcp 0.6.1
File Interpreter ABI Platform Actions
cmd_line_mcp-0.6.1-py3-none-any.whl Python 3 none any Details for cmd_line_mcp-0.6.1-py3-none-any.whl

Total release size: 104.1 kB

Release files / cmd_line_mcp-0.6.1.tar.gz

Download URL cmd_line_mcp-0.6.1.tar.gz
Size 67.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1974e620b72de6c7d32a1bc6317c837cab7af60d0dfd8c6b981cc3aa5ab44646
BLAKE2b-256 checksum
How to use checksums
b76350be4b51cfe614dd44098a587c416560e6f535d6d8a8df5a2a6bb9687953
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / cmd_line_mcp-0.6.1-py3-none-any.whl

Download URL cmd_line_mcp-0.6.1-py3-none-any.whl
Size 36.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
18621072ccddff6e1426efd1ecd94f8e015512e263f178ed71fdf8e2d56fde65
BLAKE2b-256 checksum
How to use checksums
5fc023ce0a99f6485a019fac209e6e49791c6816e951bce46019204cdaa5a70e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for cmd-line-mcp 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page