CLI MCP Server

To prepare the package for distribution using uv:

1. Sync dependencies and update lockfile:

   uv sync

2. Build package distributions:
   ```bash
uv build

(This creates source and wheel distributions in the dist/ directory) 3. Publish to PyPI:

uv publish --token {{YOUR_PYPI_API_TOKEN}}

To automatically install the CLI MCP Server for use with Claude Desktop, use the Smithery CLI tool.

npx @smithery/cli install cli-mcp-server --client claude

If you are running the server from a local repository that is not yet published, add the following configuration to your ~/Library/Application\ Support/Claude/claude_desktop_config.json file. Replace placeholders like <path/to/the/repo> and </your/desired/dir> with your actual local paths.

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "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"
      }
    }
  }
}

To use the published version of the server in Claude Desktop, add this configuration to your ~/Library/Application\ Support/Claude/claude_desktop_config.json. If the server does not appear in the UI, try running uv clean to clear your cache.

{
  "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"
      }
    }
  }
}

Since MCP servers communicate over stdio, use the MCP Inspector to debug. Replace {{your source code local directory}} with the absolute path to your local repository.

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

The run_command tool executes whitelisted CLI commands within the directories specified by ALLOWED_DIR.

Input Schema:

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

Security Constraints:

• Commands must be in ALLOWED_COMMANDS (unless set to 'all').
• Flags must be in ALLOWED_FLAGS (unless set to 'all').
• All paths must reside within ALLOWED_DIR.
• Shell operators (&&, |, >, >>) are disabled by default; enable them via ALLOW_SHELL_OPERATORS=true.

The server's security constraints and execution environment are configured using environment variables. If these are not set, the server uses default values.

When using the MCP server, command failures or security violations will return error messages in the tool response. Common error types include:

• Security violation: Occurs if a command, flag, or path is not permitted, or if shell operators are used without being enabled.
• Command timed out: Occurs if the command exceeds the COMMAND_TIMEOUT limit.
• Error: General execution failures (e.g., command not found or internal subprocess errors).

Errors are returned as TextContent objects with error=True.

The main() function serves as the primary entry point for the cli_mcp_server package. It initializes and runs the MCP server's main event loop using asyncio. This is the function you should call when executing the server as a standalone application.

from cli_mcp_server import main

if __name__ == "__main__":
    main()