Command-Line MCP Server
Run and manage safe terminal commands through an MCP server with validation, whitelisting, and session approvals.
Execute general Unix/macOS commands; write and system commands require approval.
Execute read-only commands directly (e.g.,
ls,cat,grep).List available commands grouped by read, write, and system categories.
Get help on supported commands, blocked commands, chaining rules, and usage restrictions.
Approve command types (read/write/system) for a session, optionally remembering the approval.
Approve directory access for a session, optionally remembering it.
List whitelisted and session-approved directories.
View current server configuration.
Supports validated pipes,
;,&&, and||; rejects background jobs, variables, command substitution, and subshells.Blocks dangerous commands and patterns (e.g., shells, interpreters,
sudo) with configurable whitelists, command lists, and dangerous regex patterns.
Supports .env file configuration for environment-specific settings of the MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Command-Line MCP Server list all Python files in my current directory"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 configRelated 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.
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:
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 |
| Auto |
Write |
| Required |
System |
| Required |
Blocked |
| 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
Available Tools
8 toolsapprove_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
Scored across 8 tools
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.
All tools follow a consistent verb_noun pattern (get_, approve_, execute_, list_). No mixing of conventions.
8 tools is well-scoped for a command-line execution server with permission management. Each tool serves a clear purpose.
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
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely execute shell commands on local machines through an SSH interface with session management, command execution, and sudo support.1-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseAqualityDmaintenanceEnables 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.1023 npmMIT
- AlicenseAqualityDmaintenanceEnables 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.6Apache 2.0