Install & Compatibility
Where this runs
tested against v0.2.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cli-mcp-server
✓ This library is primarily run as a server process and does not typically expose symbols for direct Python import into other applications. It is configured and interacted with by an MCP client.
cli-mcp-server is an application (a server) that is executed, rather than a Python library imported for its classes or functions into another script. Its interaction is via the Model Context Protocol.
This quickstart illustrates how an MCP client (like 'Augment Code') would be configured to connect to the `cli-mcp-server`. The Python code demonstrates setting crucial environment variables programmatically, which are then picked up by the `cli-mcp-server` process when launched. The server is typically run using `uvx cli-mcp-server` or a similar command, and clients communicate with it over the Model Context Protocol. Remember to replace placeholder paths and commands with your actual requirements and ensure `uv` is installed to run the server as per common examples.
import os
# These environment variables are critical for security and functionality.
# Adjust values to your specific needs.
os.environ['ALLOWED_DIR'] = '/tmp'
os.environ['ALLOWED_COMMANDS'] = 'ls,cat,pwd,echo'
os.environ['ALLOWED_FLAGS'] = '-l,-a,--help,--version'
os.environ['MAX_COMMAND_LENGTH'] = '1024'
os.environ['COMMAND_TIMEOUT'] = '30'
os.environ['ALLOW_SHELL_OPERATORS'] = 'false'
print('Configuring MCP client to connect to cli-mcp-server...')
print('Example MCP client configuration snippet (e.g., for Augment Code):')
print("""
{
"mcpServers": {
"cli-mcp-server": {
"command": "uvx",
"args": ["cli-mcp-server"],
"env": {
"ALLOWED_DIR": "/path/to/your/projects",
"ALLOWED_COMMANDS": "git,npm,python,ls,cat,grep,find,pytest",
"ALLOWED_FLAGS": "-l,-a,--help,--version,--oneline,run,test,status,log"
}
}
}
}
""")
print('Ensure `uv` is installed and in your PATH, and adjust `ALLOWED_DIR` and `ALLOWED_COMMANDS` for your environment.')
print('The actual cli-mcp-server application would be started via `uvx cli-mcp-server` or similar, listening for MCP client connections.')
cli-mcp-server --version
Debug
Known issues
breakingThe underlying Model Context Protocol (MCP) Python SDK is migrating from v1 (using `FastMCP`) to v2 (using `MCPServer`). This change introduces breaking changes for server implementations. `cli-mcp-server` may require updates to remain compatible with future versions of the MCP SDK and clients.fixMonitor the `cli-mcp-server` GitHub repository for updates and migration guides to the MCP Python SDK v2. Developers building upon or modifying `cli-mcp-server` should consult the official MCP migration guide for changes from `FastMCP` to `MCPServer`.
affects: <=0.2.5 (and potentially future 0.x versions)
gotchaSecurity configuration is paramount. `cli-mcp-server` is designed for secure command execution, but misconfiguring environment variables like `ALLOWED_DIR`, `ALLOWED_COMMANDS`, `ALLOWED_FLAGS`, and `ALLOW_SHELL_OPERATORS` can lead to severe security vulnerabilities, allowing unintended or malicious command execution.fixAlways review and strictly limit the `ALLOWED_DIR`, `ALLOWED_COMMANDS`, and `ALLOWED_FLAGS` to the absolute minimum necessary. Keep `ALLOW_SHELL_OPERATORS` set to `false` unless explicitly required and thoroughly understood. Implement robust validation and sanitization for any dynamic inputs.
affects: All versions
gotchaDebugging MCP servers running over standard I/O (stdio) can be challenging due to the nature of process communication.fixThe official documentation recommends using the MCP Inspector tool for the best debugging experience, which provides a web-based interface for interactive testing and inspection.
affects: All versions
gotchaMany quickstart and deployment examples for MCP servers (including `cli-mcp-server`) rely on `uv` or `uvx` for execution. Users might expect a standard `python -m` command.fixEnsure `uv` is installed and accessible in your system's PATH. If `uvx` is used, it's typically part of the `uv` installation. If you prefer `pip`, you might need to find an alternative execution method or wrap the server in a custom script.
affects: All versions
Upgrade
Version history
0.2.5latest on PyPI · released Jul 4, 2025
Audit
Dependencies
mcprequiredCore dependency for Model Context Protocol implementation.