@supercorp/shell-mcp

An MCP server that gives AI agents shell access. Provides a run_command tool for executing shell commands and returning stdout, stderr, and exit code.

Supports Streamable HTTP, SSE, and stdio transports.

Quick start

npx @supercorp/shell-mcp

This starts an HTTP server on port 8000.

Usage

Streamable HTTP (default)

npx @supercorp/shell-mcp --port 3000

SSE

npx @supercorp/shell-mcp --transport sse --port 3000

stdio

npx @supercorp/shell-mcp --transport stdio

Options

| Flag | Default | Description | |---|---|---| | --port | 8000 | Port to listen on (HTTP and SSE transports) | | --transport | http | Transport type: http, sse, or stdio | | --workdir | . | Default working directory for commands |

Tool

run_command

Execute a shell command.

Parameters:

| Name | Type | Required | Description | |---|---|---|---| | command | string | Yes | The shell command to run | | workdir | string | No | Working directory (overrides --workdir) |

Response:

{
  "stdout": "hello world\n",
  "stderr": "",
  "exitCode": 0
}

Commands have a 60-second timeout and 10 MB output buffer.

MCP client configuration

Claude Desktop

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "@supercorp/shell-mcp", "--transport", "stdio"]
    }
  }
}

HTTP client

{
  "mcpServers": {
    "shell": {
      "url": "http://localhost:8000/"
    }
  }
}

License

ISC