claude-command-runner

Claude Command Runner exposes a suite of tools that let Claude Desktop execute terminal commands, manage workflows, and stream results directly within conversations. It supports a growing set of capabilities including command execution with manual output retrieval, real-time streaming for long-running tasks, template-based command patterns, and environment intelligence to surface context like git state, Node versions, and Docker status. Users can chain commands into pipelines with conditional logic, save reusable templates, and run them with live output or parsed JSON results to build automation workflows from chat.

To use it, connect Claude Desktop to the MCP server instance (via the port and binary path configured in your environment). Once connected, use the available tools such as execute_command for simple commands, execute_pipeline to string together multiple steps with on_fail behaviors, and execute_with_streaming for long-running tasks. You can also save templates for common patterns, run saved templates with variable substitution, and inspect command output in structured JSON when using tools like execute_and_parse or get_command_output. The environment intelligence features provide context about your terminal state, and workspace profiles help you switch project contexts quickly by restoring directory state and environment variables.

Prerequisites:

• A running MCP server (as described in the repository README)
• Docker installed (if using the Docker-based runner described in this document) or an alternative runtime compatible with your environment
• Access to Claude Desktop for configuring MCP integrations

Step-by-step installation:

1. Install Docker (if not already installed)

   • macOS: https://docs.docker.com/desktop/mac/
   • Windows: https://docs.docker.com/desktop/windows/
   • Linux: follow your distro’s Docker installation guide

2. Run the Claude Command Runner container

# Pull and run the container (example image name used in this guide)
docker pull claude-command-runner-image:latest
docker run -d --name claude-command-runner -p 9876:9876 claude-command-runner-image:latest

3. Configure Claude Desktop to connect to the MCP server

• Open Claude Desktop settings and add a new MCP server entry with the following (adjust port if you changed it):

{
  "claude-command-runner": {
    "command": "/path/to/claude-command-runner/.build/release/claude-command-runner",
    "args": ["--port", "9876"],
    "env": {}
  }
}

4. If you are not using Docker, install or run the binary directly following the repository's build steps and point Claude Desktop to the executable path in the MCP settings.

5. Grant necessary permissions as described in the README (macOS Accessibility, etc.) and restart Claude Desktop.

Notes and tips:

• The MCP server exposes a growing set of tools (30 as of v5.0), including core execution, clipboard access, notifications, environment intelligence, and workspace management. Check the official Tools table in the README to discover available commands.
• When using pipelines and streaming, you can tune behavior with on_fail for each step and update_interval in streaming configurations.
• Templates are stored under the user’s home directory (e.g., ~/.claude-command-runner/templates.json) and persist across sessions.
• If you rebuild or update the binary, you may need to reconfigure macOS Accessibility permissions due to binary identity changes.
• Ensure your environment variables and paths are correctly set in the MCP config to avoid runtime errors.
• For remote or multi-terminal setups, consider using SSH-related capabilities to operate on remote hosts securely.