stitch-mcp CLI

Skill by ara.so — MCP Skills collection.

Overview

stitch-mcp is a CLI tool that bridges Google's Stitch AI-generated UI design platform with local development workflows. It enables you to:

• Preview all screens from a Stitch project on a local dev server
• Generate deployable Astro sites by mapping screens to routes
• Proxy Stitch MCP tools to coding agents with automatic token refresh
• Browse and explore design data interactively in the terminal
• Invoke MCP tools directly from the command line

The tool handles authentication, fetching HTML/CSS designs via the Stitch API, and structuring them for development or agent consumption.

Installation

Run directly with npx (no installation needed):

npx @_davideast/stitch-mcp <command>

Or install globally:

npm install -g @_davideast/stitch-mcp

Quick Start

1. Initialize Authentication

The init command sets up gcloud SDK, OAuth, and MCP client configuration:

npx @_davideast/stitch-mcp init

This wizard will:

• Install an isolated gcloud SDK (if needed)
• Guide you through OAuth authentication
• Enable the Stitch API on your project
• Generate MCP client configuration

2. Verify Setup

npx @_davideast/stitch-mcp doctor

Use --verbose flag for detailed diagnostics:

npx @_davideast/stitch-mcp doctor --verbose

3. Preview Designs Locally

Serve all screens from a project on a Vite dev server:

npx @_davideast/stitch-mcp serve -p <project-id>

This starts a local server (default: http://localhost:5173) with all project screens accessible.

4. Build an Astro Site

Generate a deployable Astro project from Stitch screens:

npx @_davideast/stitch-mcp site -p <project-id>

The command will:

• Prompt you to map screens to routes (e.g., "/" for home, "/about" for about page)
• Fetch HTML/CSS for each screen
• Generate a complete Astro project structure
• Output to ./stitch-site directory by default

Specify output directory:

npx @_davideast/stitch-mcp site -p <project-id> -o ./my-site

Authentication Methods

Method 1: Automatic OAuth (Recommended)

npx @_davideast/stitch-mcp init

Follow the wizard. Your credentials are stored in ~/.stitch-mcp/.

Method 2: API Key

Set the API key as an environment variable:

export STITCH_API_KEY="your-api-key"

This skips OAuth entirely.

Method 3: System gcloud

If you have gcloud CLI already 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 with STITCH_USE_SYSTEM_GCLOUD=1:

STITCH_USE_SYSTEM_GCLOUD=1 npx @_davideast/stitch-mcp serve -p <project-id>

Logout

npx @_davideast/stitch-mcp logout

Force logout and clear all config:

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

MCP Integration

Configure Your Agent

Add this to your MCP client config (e.g., claude_desktop_config.json, .cursor/config.json):

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

Using API key:

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

Using system gcloud:

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

Virtual Tools for Agents

The proxy exposes high-level tools that combine multiple API calls:

build_site

Builds a site from a project by mapping screens to routes. Returns HTML for each page.

Input schema:

{
  projectId: string;      // Required
  routes: Array<{
    screenId: string;     // Required
    route: string;        // Required, e.g. "/" or "/about"
  }>;
}

Example usage from CLI:

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

Prompt for agent:

Use the build_site tool to create a website from my Stitch project 123456.
Map screen abc123 to the home page, def456 to /about, and ghi789 to /contact.

get_screen_code

Retrieves a screen and downloads its HTML code content.

npx @_davideast/stitch-mcp tool get_screen_code -d '{
  "projectId": "123456",
  "screenId": "abc123"
}'

get_screen_image

Retrieves a screen and downloads its screenshot image as base64.

npx @_davideast/stitch-mcp tool get_screen_image -d '{
  "projectId": "123456",
  "screenId": "abc123"
}'

Key Commands

Exploration & Browsing

View Projects

npx @_davideast/stitch-mcp view --projects

Opens an interactive browser listing all your Stitch projects.

View Specific Project

npx @_davideast/stitch-mcp view --project <project-id>

Shows all screens in the project.

View Specific Screen

npx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id>

Interactive browser controls:

• Arrow keys: navigate
• Enter: drill into nested data
• c: copy selected value to clipboard
• s: preview HTML in browser
• o: open project in Stitch
• q: quit

Browse Screens in Terminal

npx @_davideast/stitch-mcp screens -p <project-id>

Displays an interactive list of all screens with preview and copy actions.

Tool Invocation

List All Available Tools

npx @_davideast/stitch-mcp tool

Show Tool Schema

npx @_davideast/stitch-mcp tool <tool-name> -s

Example:

npx @_davideast/stitch-mcp tool build_site -s

Invoke a Tool

npx @_davideast/stitch-mcp tool <tool-name> -d '<json-data>'

Example:

npx @_davideast/stitch-mcp tool get_screen_code -d '{
  "projectId": "123456",
  "screenId": "abc123"
}'

Development Workflow

Serve Project Locally

npx @_davideast/stitch-mcp serve -p <project-id>

Custom port:

npx @_davideast/stitch-mcp serve -p <project-id> --port 3000

Generate Astro Site

npx @_davideast/stitch-mcp site -p <project-id>

Non-interactive mode with config file:

Create routes.json:

{
  "routes": [
    { "screenId": "abc123", "route": "/" },
    { "screenId": "def456", "route": "/about" }
  ]
}

Then run:

npx @_davideast/stitch-mcp site -p <project-id> --config routes.json -o ./output

Save Screen Snapshot

npx @_davideast/stitch-mcp snapshot -p <project-id> -s <screen-id> -o ./snapshot.html

MCP Proxy

Start the proxy server for agent integration:

npx @_davideast/stitch-mcp proxy

Debug mode (logs to /tmp/stitch-proxy-debug.log):

npx @_davideast/stitch-mcp proxy --debug

Environment Variables

Common Patterns

Pattern 1: Preview All Designs Before Building

# 1. Browse available screens
npx @_davideast/stitch-mcp screens -p <project-id>

# 2. Serve locally to review designs
npx @_davideast/stitch-mcp serve -p <project-id>

# 3. Build site after confirming screens
npx @_davideast/stitch-mcp site -p <project-id>

Pattern 2: Agent-Driven Site Generation

User prompt to agent:

I have a Stitch project with ID 123456. It has three screens:
- Home page (screen ID: abc123)
- About page (screen ID: def456)
- Contact page (screen ID: ghi789)

Use the build_site tool to generate HTML for all three pages with routes /, /about, and /contact.
Then help me integrate them into my Next.js project.

The agent will use build_site and can help integrate the resulting HTML.

Pattern 3: Iterative Design Review

# View specific screen details
npx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id>

# Preview in browser (press 's' in interactive view)
# Or manually:
npx @_davideast/stitch-mcp snapshot -p <project-id> -s <screen-id> -o ./preview.html
open ./preview.html

# Get the HTML code for integration
npx @_davideast/stitch-mcp tool get_screen_code -d '{
  "projectId": "<project-id>",
  "screenId": "<screen-id>"
}'

Pattern 4: Automated Site Builds in CI

#!/bin/bash
# ci-build-stitch.sh

export STITCH_API_KEY="${STITCH_API_KEY}"
PROJECT_ID="123456"

# Generate site with predefined routes
npx @_davideast/stitch-mcp site -p "$PROJECT_ID" \
  --config ./stitch-routes.json \
  -o ./dist/stitch-site \
  --non-interactive

# Deploy the generated site
cd ./dist/stitch-site
npm install
npm run build

stitch-routes.json:

{
  "routes": [
    { "screenId": "home_abc", "route": "/" },
    { "screenId": "about_def", "route": "/about" },
    { "screenId": "contact_ghi", "route": "/contact" }
  ]
}

Troubleshooting

"Permission Denied" Errors

Symptoms: API calls fail with 403 or permission errors.

Solutions:

1. Verify your GCP role (need Owner or Editor):

   gcloud projects get-iam-policy <PROJECT_ID> \
     --flatten="bindings[].members" \
     --filter="bindings.members:user:your-email@example.com"
   

   Copy

2. Ensure billing is enabled:

   gcloud billing projects describe <PROJECT_ID>
   

   Copy

3. Enable Stitch API:

   gcloud beta services mcp enable stitch.googleapis.com --project=<PROJECT_ID>
   

   Copy

4. Run diagnostics:

   npx @_davideast/stitch-mcp doctor --verbose
   

   Copy

Authentication URL Not Appearing

Symptoms: No browser opens or URL not printed during init.

Solutions:

1. Look for URL in terminal output (5-second timeout)
2. Check for URLs starting with https://accounts.google.com
3. In proxy debug mode, check /tmp/stitch-proxy-debug.log
4. In remote environments (WSL/SSH/Docker), copy the URL manually:

   npx @_davideast/stitch-mcp init
   # Copy the URL from terminal output and open in browser
   

   Copy

"Already Authenticated" Issues

Symptoms: Shows as logged in but commands fail.

Cause: The bundled gcloud SDK has separate auth from system gcloud.

Solution:

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

API Connection Fails After Setup

Solutions:

1. Run full diagnostics:

   npx @_davideast/stitch-mcp doctor --verbose
   

   Copy

2. Re-authenticate:

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

   Copy

3. Verify project and billing:

   gcloud config get-value project
   gcloud billing projects describe $(gcloud config get-value project)
   

   Copy

WSL / SSH / Docker Environments

Symptoms: Browser-based auth doesn't work automatically.

Solution: The CLI detects these environments. Copy the OAuth URL from terminal output and open it in a browser manually. The URL will be printed to stdout with clear instructions.

MCP Proxy Not Responding

Symptoms: Agent can't connect to Stitch tools.

Solutions:

1. Run proxy with debug logging:

   npx @_davideast/stitch-mcp proxy --debug
   

   Copy

2. Check logs:

   tail -f /tmp/stitch-proxy-debug.log
   

   Copy

3. Verify MCP client config syntax:

   cat ~/.config/claude/claude_desktop_config.json | jq .
   

   Copy

4. Restart your MCP client (VS Code, Cursor, etc.)

Tool Invocation Failures

Symptoms: tool command returns errors or empty responses.

Solutions:

1. Check tool schema:

   npx @_davideast/stitch-mcp tool <tool-name> -s
   

   Copy

2. Validate JSON data:

   echo '{"projectId":"123"}' | jq .
   

   Copy

3. Test with simpler tool first:

   npx @_davideast/stitch-mcp tool list_projects
   

   Copy

4. Ensure project and screen IDs are correct:

   npx @_davideast/stitch-mcp view --projects
   

   Copy

Development & Testing

# Clone and install
git clone https://github.com/davideast/stitch-mcp.git
cd stitch-mcp
bun install

# Run locally
bun run dev init

# Run specific command
bun run dev serve -p <project-id>

# Run tests
bun test

# Build
bun run build

# Verify package
bun run verify-pack

Real-World Agent Prompts

Example 1: Site Generation

I have a Stitch project (ID: 456789) with these screens:
- Landing page: screen_landing_001
- Features page: screen_features_002
- Pricing page: screen_pricing_003

Please use the build_site tool to generate a site with:
- Landing at /
- Features at /features
- Pricing at /pricing

Then show me how to integrate the HTML into my existing React project.

Example 2: Design Review

Get the HTML code for screen abc123 from project 456789 using get_screen_code.
Then analyze the CSS and suggest improvements for mobile responsiveness.

Example 3: Batch Export

For project 456789, use get_screen_image to export all screen screenshots as base64.
Save them to a design-assets/ directory for our design system documentation.

License

Apache 2.0 © David East

Disclaimer: This is an experimental, independent project not affiliated with Google LLC or the Stitch team. Use at your own risk.