Run Command MCP Server

A Model Context Protocol (MCP) server that provides command execution capabilities with both synchronous and asynchronous streaming support.

Features

• Synchronous Command Execution: Run commands and wait for completion
• Asynchronous Command Execution: Start commands in background and monitor progress
• Real-time Output Streaming: Check command output while it's running
• Process Management: List, monitor, kill, and clean up processes
• Timeout Support: Automatically terminate long-running commands
• Multiple Transport Modes:
  • Stdio Transport: Standard MCP communication via stdin/stdout
  • HTTP Transport: RESTful API with Server-Sent Events (SSE) support for real-time notifications
• MCP Standard Compliance: Fully compliant with MCP specifications

Usage

Stdio Transport (Default)

Claude Desktop

{
  "mcpServers": {
    "run-command": {
      "command": "npx",
      "args": ["github:stilllovee/run-command-mcp"]
    }
  }
}

Or use locally after cloning:

{
  "mcpServers": {
    "run-command": {
      "command": "node",
      "args": ["PATH_TO_YOUR_REPO/index.js"]
    }
  }
}

Github Copilot

{
    "servers": {
        "run-command": {
            "type": "stdio",
            "command": "npx",
            "args": ["github:stilllovee/run-command-mcp"]
        },
    },
    "inputs": []
}

Or use locally after cloning:

{
    "servers": {
        "run-command": {
            "type": "stdio",
            "command": "node",
            "args": ["PATH_TO_YOUR_REPO/index.js"]
        }
    },
    "inputs": []
}

HTTP Transport (Streamable)

Start the HTTP server:

# Default port (8123)
npm run start:http

# Custom port
node http-server.js --port=3000

The server will be available at: http://localhost:8123/mcp

Github Copilot Configuration (HTTP)

{
    "servers": {
        "run-command-http": {
            "type": "http",
            "url": "http://localhost:8123/mcp"
        }
    },
    "inputs": []
}

Available Tools

run_command

Run a custom shell command synchronously and return the output (stdout, stderr, exit code). Blocks until command completes.

Parameters:

• command (required): The full command to execute (e.g., "echo hello world", "npm install", "git status")
• timeout (optional): Timeout in milliseconds (default: 30000)

Example:

{
  "command": "echo hello world",
  "timeout": 5000
}

start_command

Start a command asynchronously (non-blocking). Returns a process_id to check status and output later.

Parameters:

• command (required): The full command to execute (e.g., "node server.js", "npm run dev")
• timeout (optional): Timeout in milliseconds. 0 means no timeout (default: 0)

Example:

{
  "command": "node server.js",
  "timeout": 0
}

get_command_output

Get the current output and status of a running or completed async command by process_id.

Parameters:

• process_id (required): The process ID returned by start_command
• tail (optional): Only return the last N lines of output (0 = all)

Example:

{
  "process_id": "550e8400-e29b-41d4-a716-446655440000",
  "tail": 10
}

list_processes

List all tracked processes (running, completed, failed, etc.)

Parameters:

• status (optional): Filter by status: running, completed, failed, killed, error, timed_out

Example:

{
  "status": "running"
}

kill_process

Kill a running process by process_id

Parameters:

• process_id (required): The process ID to kill

Example:

{
  "process_id": "550e8400-e29b-41d4-a716-446655440000"
}

clear_processes

Clear finished processes from memory. If process_id is provided, clears that specific process. Otherwise clears all non-running processes.

Parameters:

• process_id (optional): Specific process ID to clear

Example:

{
  "process_id": "550e8400-e29b-41d4-a716-446655440000"
}

Usage Examples

Example 1: Run a simple synchronous command

User: Run "echo hello world"
AI: Uses run_command to execute and get immediate results

Example 2: Start a long-running server

User: Start my Node.js server
AI: Uses start_command to start server in background
AI: Uses get_command_output to check if server started successfully

Example 3: Monitor build progress

User: Build my project and show me the progress
AI: Uses start_command to start build
AI: Periodically uses get_command_output to check build logs
AI: Reports progress to user in real-time

Example 4: Run Azure Functions locally

User: Start my Azure Functions app
AI: Uses start_command with "func start"
AI: Monitors output with get_command_output
AI: Shows compilation progress and when functions are ready

Use Cases

• Development Servers: Start and monitor Node.js, Python, or other development servers asynchronously
• Build Processes: Run and monitor long build processes (webpack, tsc, etc.)
• Testing: Run test suites and monitor results
• System Administration: Execute system commands and check results
• Log Monitoring: Start services and continuously check their logs