CLI MCP Server
Securely run whitelisted CLI commands within an allowed directory via MCP.
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx @smithery/cli install cli-mcp-server --client claudePaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"cli-mcp-server": {
"command": "uvx",
"args": [
"cli-mcp-server"
],
"env": {
"ALLOWED_DIR": "</your/desired/dir>",
"ALLOWED_COMMANDS": "ls,cat,pwd,echo",
"ALLOWED_FLAGS": "-l,-a,--help,--version",
"MAX_COMMAND_LENGTH": "1024",
"COMMAND_TIMEOUT": "30",
"ALLOW_SHELL_OPERATORS": "false"
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.10+
- MCP protocol library
- uv / uvx (for running the server)
About CLI MCP Server
CLI MCP Server is a secure MCP server implementation for executing controlled command-line operations. It enforces command and flag whitelisting (with an 'all' opt-out), path-traversal prevention, working-directory restriction, shell-operator injection protection, execution timeouts, and command-length limits, giving LLM applications controlled CLI access while maintaining security. Configuration is done via environment variables, with ALLOWED_DIR required.
Tools & capabilities (2)
run_commandExecutes whitelisted CLI commands within allowed directories. Takes a single command string (e.g., 'ls -l' or 'cat file.txt'). Shell operators are not supported unless ALLOW_SHELL_OPERATORS=true; commands and flags must be whitelisted unless set to 'all'; all paths are validated to be within ALLOWED_DIR.
show_security_rulesDisplays the current security configuration and restrictions, including the working directory, allowed commands, allowed flags, and security limits (max command length and timeout).
When to use it
- Giving an LLM controlled, sandboxed CLI access scoped to a single directory
- Running a fixed whitelist of safe commands (e.g., ls, cat, pwd, echo) from Claude Desktop
- Inspecting files and directory contents through an agent without granting full shell access
- Enforcing command timeouts and length limits on automated command execution
Security notes
Shell operators (&&, |, >, >>) are blocked by default but can be enabled with ALLOW_SHELL_OPERATORS=true. Commands must be whitelisted unless ALLOWED_COMMANDS='all'; flags must be whitelisted unless ALLOWED_FLAGS='all'. Setting either to 'all' removes that restriction entirely. All paths are validated and normalized to be within ALLOWED_DIR, with path-traversal prevention and symlink resolution. Execution is bounded by MAX_COMMAND_LENGTH and COMMAND_TIMEOUT.
CLI MCP Server FAQ
How do I allow any command or flag?
Set ALLOWED_COMMANDS or ALLOWED_FLAGS to 'all'. This removes the respective whitelist restriction; otherwise only the comma-separated listed values are permitted.
Why are shell operators like && and | not working?
Shell operators (&&, ||, |, >, >>) are blocked by default to prevent injection. Enable them by setting ALLOW_SHELL_OPERATORS=true.
What configuration is required?
ALLOWED_DIR is required and has no default; it sets the base directory for command execution. All other variables (ALLOWED_COMMANDS, ALLOWED_FLAGS, MAX_COMMAND_LENGTH, COMMAND_TIMEOUT, ALLOW_SHELL_OPERATORS) have defaults.
The server isn't showing up in Claude Desktop. What can I do?
Per the docs, if it's not working or showing in the UI, clear your cache via 'uv clean'.
Alternatives to CLI MCP Server
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
LSP-powered coding agent toolkit: semantic symbol search, references and structural edits.
Compare CLI MCP Server with: