shell-mcp

A deliberately small MCP server that exposes a single tool, run_shell, for executing arbitrary shell commands over Streamable HTTP.

It uses the stable v2 Model Context Protocol TypeScript SDK (@modelcontextprotocol/server and @modelcontextprotocol/node) and runs on Node.js 20+.

Tool

run_shell

The result includes stdout, stderr, exit code, terminating signal, duration, timeout state, and whether the output limit was exceeded.

Related MCP server: mcp2term

Run

npm install
npm run build
npm start

The MCP endpoint defaults to:

http://127.0.0.1:3000/mcp

For development:

npm run dev

Configuration

Example network bind:

HOST=0.0.0.0 \
SHELL_MCP_TOKEN='use-a-long-random-secret' \
npm start

Configure the MCP client to send:

Authorization: Bearer use-a-long-random-secret

For anything beyond a trusted local network, put the endpoint behind TLS and an authenticated reverse proxy rather than exposing the Node process directly.

Examples

Bash:

{
  "command": "uname -a && pwd",
  "shell": "bash"
}

PowerShell:

{
  "command": "Get-ChildItem Env: | Select-Object -First 5",
  "shell": "pwsh"
}

Development

npm run check

Design

• One MCP tool; no resources or prompts.

• Streamable HTTP only; no stdio transport.

• Stateless MCP handler with a fresh McpServer per request, following the v2 SDK serving model.

• Explicit shell invocation for POSIX shells, PowerShell, and cmd.exe.

• Process-tree termination on timeout or output overflow.

• Loopback binding by default, with bearer authentication required for non-loopback binds.

License

MIT