shell-mcp

Remote shell + file operations MCP server. Core is pure stdlib (fully unit-testable); only server.py depends on mcp / starlette / uvicorn.

Features

• Streamable HTTP at /mcp (POST). No long-lived connections, safe behind buffered reverse proxies.

• Bearer token auth (constant-time compare) + optional IP allowlist + /health endpoint.

• Two execution modes: restricted (command allowlist, no shell operators) / unrestricted (full shell). Windows: unrestricted mode uses cmd.exe or PowerShell; POSIX: $SHELL -lc.

• Reliable process execution: stdout+stderr merged in real order; output streamed to temp file (bounded memory, no pipe deadlock); children in their own process group; timeout kills the entire process tree (POSIX killpg / Windows taskkill /T).

• Background tasks: run_command(background="always") for dev servers / builds; task(action="wait"|"output"|"cancel"|"list") to manage.

• Sync-first by default: run_command waits up to SHELL_MCP_WAIT_SECONDS (30s) then auto-backgrounds. Short commands return results inline.

• Safe editing: edit_file exact replacement + atomic write + unified diff; apply_patch multi-file atomic; expected_sha256 precondition prevents stale-read conflicts (returns FILE_CHANGED without touching files).

• Code search: grep (ripgrep preferred, pure-Python fallback) + glob (sort by path or modified time).

• Encoding consistency: auto-detect (UTF-8 / Windows code pages / GB18030), preserve original encoding on write.

• Output governance: line+byte caps, tail truncation, full output spilled to OS temp dir (shell-mcp-spool/), auto-pruned.

• Machine-readable errors: all failures return code (e.g. OLD_TEXT_NOT_FOUND, FILE_NOT_FOUND) + structured fields.

• Audit log: JSON lines, auto-rotated.

• Cross-platform: Windows / macOS / Linux. Platform-specific code gated behind os.name == "nt".

Related MCP server: MCP Remote Code

Quick Start

pip install -r requirements.txt
cp .env.example .env   # fill SHELL_MCP_TOKEN (openssl rand -hex 32)
# macOS / Linux:
./run.sh
# Windows:
run.bat

Client config (Streamable HTTP):

{
  "url": "http://127.0.0.1:8000/mcp",
  "headers": { "Authorization": "Bearer <SHELL_MCP_TOKEN>" }
}

Print a ready-to-paste client snippet (with real token + auto-detected Tailscale URL):

python -m shell_mcp.server --print-client

Tools (13)

Low-level tools (task_output, kill_task, list_tasks, delete_file, make_dir, rename_file) hidden by default; enable with SHELL_MCP_EXPOSE_LOWLEVEL=true.

Configuration

All via environment variables (see .env.example for full list):

Exposing via Tailscale

Keep SHELL_MCP_HOST=127.0.0.1 (never bind to public interfaces). Let tailscaled handle TLS:

# Tailnet-only (auto-HTTPS):
tailscale serve --bg 8000

# Public internet (Funnel; requires Funnel enabled in admin console):
tailscale funnel --bg 8000

# Check status / stop:
tailscale serve status
tailscale funnel --bg off 8000

Client URL: https://<machine>.<tailnet>.ts.net/mcp

Security notes:

• Funnel = anyone on the internet can reach this port. Use a long random token (openssl rand -hex 32). Keep SHELL_MCP_UNRESTRICTED=false.

• Tailscale serve forwards real client IPs (100.x.y.z). Pin them with SHELL_MCP_ALLOWED_IPS for token+IP dual defense (tailnet only; don't use with Funnel).

• Funnel only supports ports 443/8443/10000 for HTTPS. TLS terminated by Tailscale.

• Audit log records commands and paths. Restrict file permissions on the log.

Architecture

shell_mcp/
├── config.py          # env → Config; SessionState
├── errors.py          # ToolFailure → MCP isError
├── paths.py           # Path resolution + sandbox enforcement
├── encoding.py        # Auto-detect encoding (UTF-8 / Windows / GB18030)
├── output.py          # Line+byte truncation, spool spill, pruning
├── process.py         # Command parse/execute: merged output, file capture, tree kill
├── tasks.py           # Background task registry
├── mutation_queue.py  # Per-path serialized write queue
├── editing.py         # Transactional edits: validate → atomic write → diff
├── audit.py           # JSON lines audit log
├── tools/
│   ├── shell.py       # run_command / task
│   ├── files.py       # File tools (read/write/edit/patch)
│   ├── search.py      # grep / glob
│   └── audit.py       # outline / review_file
└── server.py          # FastMCP + auth middleware (only third-party deps)

spool:// Resources

Truncated command output and background task logs are served as spool://<name> MCP resources. Tool results include full_output_resource / log_resource fields. Files live in the OS temp directory (shell-mcp-spool/) and are auto-pruned.

Design: Stale-Read Protection

read_file(path) → {text, sha256}
write_file(path, content, expected_sha256=<from read>)
→ server re-reads file, computes sha256(disk)
→ match? write. mismatch? FILE_CHANGED (file untouched)

No server-side cache. The SHA256 is computed from disk at read time and re-verified at write time. This is optimistic concurrency (ETag/If-Match pattern), not a cache.

Tests

Core is dependency-free; run directly:

python3 -m unittest discover -s tests -v

License

MIT — see LICENSE.