Command-Line MCP Server
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:
- Pattern matching — rejects configured dangerous patterns (writes to system paths,
tar --to-command, etc.) - Parsing — the command is parsed by a strict lexer; unsupported shell syntax is rejected
- Command classification — each command must be in the read, write or system list, and not blocked
- Path check — every path, glob match and redirect target in every command must be whitelisted or session-approved
- 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,shutdownand similar; configurable. - Dangerous patterns — configurable regexes, by default covering writes to system paths,
rm -rf /,tarcommand execution andfind -execwithsh,bash,zsh,ksh,csh,fish,python/python2/python3,perl,ruby,nodeorenv. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.