Cli MCP Server

What MladenSU/cli-mcp-server MCP server does

MladenSU/cli-mcp-server MCP server exposes a restricted command-line interface through MCP. It is intended for setups where an AI application needs to inspect files, query directories, or run other approved commands without granting unrestricted shell access. The server applies policy checks before execution and limits operations to a configured base directory.

The project targets Python 3.10 or newer and is distributed under the MIT License. It communicates over stdio, making it suitable for local MCP clients such as Claude Desktop.

How it works

The server reads its execution policy from environment variables. ALLOWED_DIR defines the directory boundary, while ALLOWED_COMMANDS and ALLOWED_FLAGS specify which commands and options may be used. Both allow the special value all, although using that value removes the corresponding whitelist restriction.

Each request is passed through validation before execution. Path normalization, traversal checks, and symlink resolution help keep file access within the permitted directory. Shell operators such as &&, pipes, and redirection are blocked by default and can be enabled explicitly with ALLOW_SHELL_OPERATORS=true.

Execution is also constrained by MAX_COMMAND_LENGTH and COMMAND_TIMEOUT. The default command length is 1024 characters and the default timeout is 30 seconds. Validation or execution failures are reported with specific error categories, including security, timeout, path, format, and command execution errors.

Setup and configuration

MladenSU/cli-mcp-server MCP server can be launched from its published package with uvx cli-mcp-server, or from a checked-out repository using the documented uv command. A working configuration must provide ALLOWED_DIR; the other settings have defaults.

For Claude Desktop, add an MCP server entry that uses uvx with cli-mcp-server as its argument. Put the policy variables in that entry’s env object. A typical policy might allow ls, cat, and pwd, permit selected flags, retain the 1024-character limit, use a 30-second timeout, and leave shell operators disabled.

Developers working from source can synchronize dependencies with uv sync and build distributions with uv build. The repository also documents publishing through uv publish, which requires a PyPI token.

Tools and capabilities

MladenSU/cli-mcp-server MCP server provides two documented tools:

• run_command accepts one command string, such as ls -l or cat file.txt, and executes it after policy validation.
• show_security_rules reports the active working directory, command and flag allowlists, maximum command length, and timeout.

The implementation supports asynchronous operations and returns detailed errors when requests violate the configured rules or when execution fails.

Limitations and notes

This server does not provide unrestricted shell access by default. Commands and flags must be allowed, paths must remain under ALLOWED_DIR, and shell operators remain unavailable unless explicitly enabled. Setting either whitelist to all broadens access and should be evaluated against the intended security boundary.

Because the server runs over stdio, client configuration must start the local process rather than connect to a hosted endpoint. The project recommends MCP Inspector for debugging stdio-based development configurations.