What is Mcp Cli Exec

mcp-cli-exec is a powerful CLI command execution MCP server that allows users to run shell commands with structured output, focusing specifically on command execution functionality.

Use cases

Use cases include running build scripts, executing deployment commands, automating testing processes, and managing server configurations.

How to use

To use mcp-cli-exec, you can execute commands using the cli-exec-raw for raw command execution or cli-exec for executing one or more commands in a specified working directory. Commands can be sent in JSON format with options for timeouts and working directories.

Key features

Key features include executing raw CLI commands with structured output, handling errors gracefully, supporting single and chained commands, returning detailed execution results including stdout, stderr, exit code, and execution duration.

Where to use

mcp-cli-exec can be used in software development environments, CI/CD pipelines, and any scenario where automated command execution is required.

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:

{
  "command": "echo Hello World"
}

With timeout:

{
  "command": "long-running-script.sh",
  "timeout": 300000
}

cli-exec

Single command in specific directory:

{
  "workingDirectory": "/path/to/project",
  "commands": "npm install"
}

Multiple commands (all run in the same working directory):

{
  "workingDirectory": "C:\\project",
  "commands": [
    "dir /b",
    "npm run build"
  ]
}

Installation

Optionally install from npm:

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:

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

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

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

pnpm install

Build the server:

pnpm run build

For development with auto-rebuild:

pnpm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. The MCP Inspector provides helpful debugging tools:

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