stitch-mcp

A CLI for moving AI-generated UI designs into your development workflow — preview them locally, build sites from them, and feed them to coding agents.

Why

AI-generated designs in Google's Stitch platform live as HTML/CSS behind an API. Getting them into a local development environment — for previewing, building, or handing off to coding agents — requires fetching, serving, and structuring them. stitch-mcp handles this through a set of CLI commands that connect to Stitch.

Quick start

# Set up authentication and MCP client config
npx @_davideast/stitch-mcp init

# Serve all project screens on a local dev server
npx @_davideast/stitch-mcp serve -p <project-id>

# Build an Astro site by mapping screens to routes
npx @_davideast/stitch-mcp site -p <project-id>

Features

• Preview designs locally — serve all screens from a project on a Vite dev server
• Build an Astro site from your designs — map screens to routes and generate a deployable project
• Give your agent design context — proxy Stitch tools to your IDE's coding agent with automatic token refresh
• Explore your design data — browse projects, screens, and metadata in the terminal or via CLI
• Browse projects in your terminal — navigate screens interactively with copy, preview, and open actions
• Set up in one command — guided wizard handles gcloud, auth, and MCP client configuration

MCP integration

Add this to your MCP client config to give coding agents access to Stitch tools:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"]
    }
  }
}

Supported clients: VS Code, Cursor, Claude Code, Gemini CLI, Codex, OpenCode.

Virtual tools

The proxy exposes these tools alongside the upstream Stitch MCP tools. They combine multiple API calls into higher-level operations for coding agents:

• build_site — Builds a site from a project by mapping screens to routes. Returns the design HTML for each page.
• get_screen_code — Retrieves a screen and downloads its HTML code content.
• get_screen_image — Retrieves a screen and downloads its screenshot image as base64.

build_site input schema:

{
  "projectId": "string (required)",
  "routes": [
    {
      "screenId": "string (required)",
      "route": "string (required, e.g. \"/\" or \"/about\")"
    }
  ]
}

Example:

npx @_davideast/stitch-mcp tool build_site -d '{
  "projectId": "123456",
  "routes": [
    { "screenId": "abc", "route": "/" },
    { "screenId": "def", "route": "/about" }
  ]
}'

Explore your designs

Use view and tool to browse your design data and understand what's available before prompting agents.

# Browse all projects
npx @_davideast/stitch-mcp view --projects

# Inspect a specific screen
npx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id>

# Invoke any MCP tool from the CLI
npx @_davideast/stitch-mcp tool [toolName]

Inside the view browser: c copies the selected value, s previews HTML in your browser, o opens the project in Stitch, and q quits. Use arrow keys to navigate and Enter to drill into nested data.

Run tool without a name to list all available tools, or with -s to see a tool's schema.

Installation

Run directly with npx (no install needed):

npx @_davideast/stitch-mcp <command>

Or install globally:

npm install -g @_davideast/stitch-mcp
stitch-mcp <command>

Commands

| Command | Description | |---------|-------------| | Setup | | | init | Set up auth, gcloud, and MCP client config | | doctor | Verify configuration health | | logout | Revoke credentials | | Development | | | serve -p <id> | Preview project screens locally | | screens -p <id> | Browse screens in terminal | | view | Interactive resource browser | | Build | | | site -p <id> | Generate Astro project from screens | | snapshot | Save screen state to file | | Integration | | | tool [name] | Invoke MCP tools from CLI | | proxy | Run MCP proxy for agents |

Run any command with --help for full options.

Authentication

Automatic (recommended): Run init and follow the wizard. It handles gcloud installation, OAuth, credentials, and project setup.

npx @_davideast/stitch-mcp init

API key: Set the STITCH_API_KEY environment variable to skip OAuth entirely.

export STITCH_API_KEY="your-api-key"

Manual (existing gcloud): If you already have gcloud configured:

gcloud auth application-default login
gcloud config set project <PROJECT_ID>
gcloud beta services mcp enable stitch.googleapis.com --project=<PROJECT_ID>

Then use the proxy with STITCH_USE_SYSTEM_GCLOUD=1:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"],
      "env": {
        "STITCH_USE_SYSTEM_GCLOUD": "1"
      }
    }
  }
}

Environment variables

| Variable | Description | |----------|-------------| | STITCH_API_KEY | API key for direct authentication (skips OAuth) | | STITCH_ACCESS_TOKEN | Pre-existing access token | | STITCH_USE_SYSTEM_GCLOUD | Use system gcloud config instead of isolated config | | STITCH_PROJECT_ID | Override project ID | | GOOGLE_CLOUD_PROJECT | Alternative project ID variable | | STITCH_HOST | Custom Stitch API endpoint |

Troubleshooting

"Permission Denied" errors

Ensure you have Owner or Editor role, billing is enabled, and the Stitch API is enabled. Run doctor --verbose to diagnose.

Authentication URL not appearing

The tool prints authentication URLs to the terminal with a 5-second timeout. Look for a URL starting with https://accounts.google.com. If using proxy with --debug, check /tmp/stitch-proxy-debug.log.

Already authenticated but showing logged in

The bundled gcloud SDK maintains separate authentication from your global gcloud installation. To fully clear authentication:

npx @_davideast/stitch-mcp logout --force --clear-config

API connection fails after setup

Run doctor --verbose to diagnose. Verify your project has billing and the Stitch API enabled. If issues persist, re-authenticate:

npx @_davideast/stitch-mcp logout --force
npx @_davideast/stitch-mcp init

WSL / SSH / Docker environments

The CLI detects WSL, SSH sessions, Docker containers, and Cloud Shell. In these environments, browser-based auth may not work automatically. Copy the OAuth URL from your terminal and open it in a browser manually.

Development

# Install dependencies
bun install

# Run locally
bun run dev init

# Run tests
bun test

# Build
bun run build

# Verify package
bun run verify-pack

License

Apache 2.0 © David East

Disclaimer

[!WARNING] Experimental Project - This is an independent, experimental tool.

This project is:

• NOT affiliated with, endorsed by, or sponsored by Google LLC, Alphabet Inc., or the Stitch API team
• Provided AS-IS with NO WARRANTIES of any kind
• NOT guaranteed to be maintained, secure, or compatible with future API versions

"Stitch" and "Google Cloud" are trademarks of Google LLC.

USE AT YOUR OWN RISK.