@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