mcp-cli-exec

# mcp-cli-exec MCP Server A powerful CLI command execution MCP server that enables running shell commands with structured output. This package focuses specifically on command execution functionality, differentiating it from other MCP CLI tools. ## Features ### Tools #### cli-exec-raw Execute a raw CLI command and return structured output - Takes a command string and optional timeout (default: 5 minutes) - Returns detailed execution results including stdout, stderr, exit code - Handles errors gracefully with structured error responses #### cli-exec Execute one or more CLI commands in a specific working directory - Supports single commands, && chained commands, or array of commands - All commands execute in the specified working directory - Returns detailed results for each command: - Success/failure status - Exit code - stdout and stderr (ANSI codes stripped) - Execution duration - Working directory - Stops on first command failure - Optional timeout per command (default: 5 minutes) Note: Due to execution context limitations, each command runs independently. Directory changes (cd) within commands do not affect subsequent commands. All commands execute in the initially specified working directory. ### Output Format Commands return structured results including: - Success/failure status - Exit code - stdout and stderr (with ANSI codes stripped) - Execution duration - Working directory - Detailed error information if applicable ### Example Usage #### cli-exec-raw Simple command execution: ```json { "command": "echo Hello World" } ``` With timeout: ```json { "command": "long-running-script.sh", "timeout": 300000 } ``` #### cli-exec Single command in specific directory: ```json { "workingDirectory": "/path/to/project", "commands": "npm install" } ``` Multiple commands (all run in the same working directory): ```json { "workingDirectory": "C:\\project", "commands": [ "dir /b", "npm run build" ] } ``` ## Installation Optionally install from npm: ```bash npm install -g mcp-cli-exec # or with pnpm pnpm add -g mcp-cli-exec ``` Or just use npx in your configuration ### For Cline VSCode Extension Add to `%APPDATA%/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`: ```json { "mcpServers": { "mcp-cli-exec": { "command": "npx", "args": ["-y", "mcp-cli-exec"] } } } ``` ### For Claude Desktop Add to the appropriate config file: Windows: `%APPDATA%/Claude/claude_desktop_config.json` MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "mcp-cli-exec": { "command": "npx", "args": ["-y", "mcp-cli-exec"] } } } ``` ### Special Windows Configuration If you encounter the ENOENT spawn npx issue on Windows, use this alternative configuration that specifies the full paths: ```json { "mcpServers": { "mcp-cli-exec": { "command": "C:\\Users\\jim\\AppData\\Roaming\\nvm\\v22.1.0\\node.exe", "args": [ "C:\\Users\\jim\\AppData\\Roaming\\npm\\node_modules\\npm\\bin\\npx-cli.js", "-y", "mcp-cli-exec" ] } } } ``` ## Development Install dependencies: ```bash pnpm install ``` Build the server: ```bash pnpm run build ``` For development with auto-rebuild: ```bash pnpm run watch ``` ### Debugging Since MCP servers communicate over stdio, debugging can be challenging. The MCP Inspector provides helpful debugging tools: ```bash pnpm run inspector ``` This will provide a URL to access the inspector in your browser, where you can: - View all MCP messages - Inspect request/response payloads - Test tools interactively - Monitor server state ## Error Handling The server includes comprehensive error handling: - Input validation for all tool parameters - Structured error responses - Command timeout handling - Working directory validation - ANSI code stripping for clean output ## Technical Details - Built with TypeScript and the MCP SDK - Uses execa for reliable command execution - Default command timeout: 5 minutes - Supports Windows and Unix-like systems (use appropriate commands for your OS, e.g., 'dir' vs 'ls') - Executes commands sequentially, stopping on first failure - Each command runs independently in the specified working directory