Command-line Interface for MCP Clients

0.2.5 · active · verified Wed Apr 15

The cli-mcp-server library (version 0.2.5) provides a secure Model Context Protocol (MCP) server that enables controlled execution of command-line operations with extensive security features. It allows AI agents and clients to interact with the system via CLI commands, enforcing policies like command whitelisting, path validation, shell operator blocking, and execution timeouts. The library appears to be actively maintained, with ongoing development and contributions to the Model Context Protocol ecosystem.

Warnings

breaking The 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.
Fix: Monitor 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`.
gotcha Security 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.
Fix: Always 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.
gotcha Debugging MCP servers running over standard I/O (stdio) can be challenging due to the nature of process communication.
Fix: The official documentation recommends using the MCP Inspector tool for the best debugging experience, which provides a web-based interface for interactive testing and inspection.
gotcha Many 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.
Fix: Ensure `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.

Install

pip install cli-mcp-server Install Package

Imports

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.

Quickstart

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.')

view raw JSON →