Run Command

You can run and manage commands with an MCP server that supports both synchronous execution and asynchronous streaming. It lets you run commands, watch their output in real time, manage long-running processes, and choose between a standard stdio-based transport or an HTTP API with real-time notifications.

How to use

Choose your preferred transport and connect your MCP client. You can run commands synchronously to get immediate results, or start commands asynchronously to monitor progress and logs over time. Use the HTTP transport when you want real-time updates via streaming HTTP, or use stdio for local integrations that communicate through standard input and output.

Typical usage flows include starting a long-running server or build process, then polling for progress and final results. You can list, inspect, or terminate running processes, and clear finished ones to keep memory usage in check. All actions are exposed as distinct endpoints or commands that you invoke from your MCP client.

How to install

Prerequisites: you need Node.js and npm installed on your machine to run the MCP server locally. You can verify installations with node -v and npm -v.

1. Install dependencies for the HTTP-based server (if you plan to run the HTTP transport locally). Run the server with the appropriate start command shown in the examples.

2. If you prefer the stdio version, ensure you have npx and node available. You will use either a prebuilt MCP package via npx or run it directly from a local repository.

Configuration and usage configurations

There are two primary transport configurations you may encounter. The HTTP transport exposes an endpoint at a configurable URL and streams real-time output to clients. The stdio transport runs locally and communicates through standard input and output.

HTTP configuration example shows the remote URL you connect to and does not require an on-device script path. The stdio configuration shows how to invoke the MCP server locally with the exact command and arguments needed to start it.

Tools and endpoints

Available tools let you run commands, start asynchronous commands, fetch outputs, list and manage processes, and clear completed tasks.

Examples of configurations you can use

{
  "mcpServers": [
    {
      "type": "http",
      "name": "run_command_http",
      "url": "http://localhost:8123/mcp",
      "args": []
    },
    {
      "type": "stdio",
      "name": "run_command_desktop",
      "command": "npx",
      "args": ["github:stilllovee/run-command-mcp"]
    },
    {
      "type": "stdio",
      "name": "run_command_copilot",
      "command": "node",
      "args": ["PATH_TO_YOUR_REPO/index.js"]
    }
  ]
}

Notes on use with security and data handling

Only run commands you trust and ensure proper access controls for the HTTP endpoint. Do not expose command execution endpoints publicly without authentication and authorization checks.

Troubleshooting

If commands aren’t starting, verify the transport configuration matches how you connect your MCP client (http vs stdio). Check that the server URL is reachable for HTTP transport and that the local runtime command and arguments are correct for stdio transport. Review process lists to identify stuck or failed tasks, and use the clear feature to remove finished tasks from memory.

Notes

The server supports synchronous execution for immediate results and asynchronous execution for ongoing processes with real-time streaming of output.

Available tools

run_command

Run a shell command synchronously and return stdout, stderr, and exit code. Waits for completion before returning.

start_command

Start a command asynchronously. Returns a process_id to monitor and retrieve output later.

get_command_output

Fetch current output and status for a running or completed async command by its process_id. Supports tailing the output lines.

list_processes

List all tracked processes with optional filtering by status such as running, completed, failed, killed, error, or timed_out.

kill_process

Terminate a running process by its process_id.

clear_processes

Remove finished or specific processes from memory to free resources.