@midlyr/sst-puppeteer-mcp

An MCP server for driving sst dev — gives AI agents the full interactive-TUI feature set (per-pane restart, stream events, log tail, redeploy waits) plus a passthrough for one-shot SST subcommands.

Concepts

• Session — one running sst dev process for a given (projectDir, stage). Created by start_session, identified by a sessionId. The whole multiplexer, the event stream, the log directory — all scoped to one session.
• Command — one pane inside a session, declared under dev.command in sst.config.ts (e.g. api, web, worker, ngrok). Identified by name within a session.

Sessions are stored on disk at ~/.sst-puppeteer/sessions/<sessionId>/ and survive MCP server restarts. Calling start_session for an already-running (projectDir, stage) is idempotent — it returns the existing sessionId with reused: true.

Install & register

Requires Node.js ≥22. Pick your host below; all snippets use npx -y @midlyr/sst-puppeteer-mcp so there's nothing to install ahead of time.

claude mcp add sst-puppeteer -s user -- npx -y @midlyr/sst-puppeteer-mcp

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sst-puppeteer": {
      "command": "npx",
      "args": ["-y", "@midlyr/sst-puppeteer-mcp"]
    }
  }
}

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "sst-puppeteer": {
      "command": "npx",
      "args": ["-y", "@midlyr/sst-puppeteer-mcp"]
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sst-puppeteer": {
      "command": "npx",
      "args": ["-y", "@midlyr/sst-puppeteer-mcp"]
    }
  }
}

Add to ~/.config/zed/settings.json under context_servers:

{
  "context_servers": {
    "sst-puppeteer": {
      "command": {
        "path": "npx",
        "args": ["-y", "@midlyr/sst-puppeteer-mcp"]
      }
    }
  }
}

codex mcp add sst-puppeteer -- npx -y @midlyr/sst-puppeteer-mcp

Restart the host after registering.

Tools

The agent gains 12 tools:

• start_session, list_sessions, stop_session, wait_for_ready
• list_commands, start_command, restart_command, stop_command
• read_command_logs, wait_for_next_ready, get_command_status
• run_sst — passthrough for any other one-shot SST subcommand (deploy, remove, secrets, unlock…)

Talk to it

"Start sst in /path/to/app on stage dev, wait for ready, then restart the api service and tail its logs."

The agent calls start_session({ projectDir, stage: 'dev' }), then wait_for_ready, restart_command, read_command_logs.

Repo: https://github.com/midlyrAI/sst-puppeteer

Disclaimer: Independent community project. Not affiliated with Anomaly Innovations (sst.dev) or Google (Puppeteer). Both names used nominatively.

License: MIT