# @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

```bash
npx @supercorp/shell-mcp
```

This starts an HTTP server on port 8000.

## Usage

### Streamable HTTP (default)

```bash
npx @supercorp/shell-mcp --port 3000
```

### SSE

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

### stdio

```bash
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:**

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

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

## MCP client configuration

### Claude Desktop

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

### HTTP client

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

## License

ISC