# MCP stdio ShellGuard

Adds an allowlist, sandbox limits and replay detection around shell calls in MCP servers, plus a CLI that audits source files for risky patterns.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: studiomeyer-io
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/studiomeyer-io/mcp-stdio-shellguard
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-stdio-shellguard

## What it does

MCP stdio ShellGuard targets the attack class where an MCP server passes raw user input into a shell command. It ships as three layers you can adopt one at a time.

The library layer gives you `guardExec` and `guardSpawn` as replacements for `child_process` calls. Nothing runs until you register a tool with `AllowlistRegistry`, naming the executable and the argument patterns it accepts. Sandbox profiles cap runtime, output size and file descriptors; a replay window flags the same invocation twice. You can tighten limits per call, never loosen them past the profile.

The audit CLI `mcp-shellguard-audit scan <path>` parses the AST and reports 12 rule hits, from a missing timeout to input interpolated straight into `exec`. Exit code `1` means findings, which makes it usable as a CI gate. Node.js 20 or newer and `@modelcontextprotocol/sdk` ^1.29.0 are required, so an older runtime won't start the server at all.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add stdio-shellguard -- npx -y mcp-stdio-shellguard
```

### Codex

**Platform CLI**
```bash
codex mcp add mcp-stdio-shellguard -- npx -y mcp-stdio-shellguard
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-stdio-shellguard": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-stdio-shellguard"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-stdio-shellguard": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mcp-stdio-shellguard"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-stdio-shellguard npx -y mcp-stdio-shellguard
```

## When to use it
- find template literals that pipe user input into `exec`
- block commands outside a registered tool list
- cap runtime and output size of spawned processes
- spot the same command invoked twice
- gate a CI pipeline on shell-call audit findings

## Example prompts
- Scan `./src` for shell-injection patterns and return the report as markdown
- Register a `git-log` tool for `/usr/bin/git` that only accepts `log --oneline -n`
- Check whether this command with this hash already ran in the replay window

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12110
- [Robin: AI-Powered Dark Web OSINT](https://affpapa.org/en/nevibecode/mcp/robin-ai-powered-dark-web-osint.md) — MCP server · ★ 7718
- [jshookmcp](https://affpapa.org/en/nevibecode/mcp/jshookmcp.md) — MCP server · ★ 2066
- [OpenOSINT](https://affpapa.org/en/nevibecode/mcp/openosint.md) — MCP server · ★ 1816

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md