stitch-mcp-cli

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

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

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:

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"

Ensure billing is enabled:

gcloud billing projects describe <PROJECT_ID>

Enable Stitch API:

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

Run diagnostics:

npx @_davideast/stitch-mcp doctor --verbose

Authentication URL Not Appearing

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

Solutions:

Look for URL in terminal output (5-second timeout)
Check for URLs starting with https://accounts.google.com
In proxy debug mode, check /tmp/stitch-proxy-debug.log

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

"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:

Run full diagnostics:

npx @_davideast/stitch-mcp doctor --verbose

Re-authenticate:

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

Verify project and billing:

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

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:

Run proxy with debug logging:

npx @_davideast/stitch-mcp proxy --debug

Check logs:
```
tail -f /tmp/stitch-proxy-debug.log
```

Verify MCP client config syntax:

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

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

Tool Invocation Failures

Symptoms: tool command returns errors or empty responses.

Solutions:

Check tool schema:

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

Validate JSON data:
```
echo '{"projectId":"123"}' | jq .
```

Test with simpler tool first:

npx @_davideast/stitch-mcp tool list_projects

Ensure project and screen IDs are correct:

npx @_davideast/stitch-mcp view --projects

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

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

About this skill

Overview

Installation

Quick Start

1. Initialize Authentication

2. Verify Setup

3. Preview Designs Locally

4. Build an Astro Site

Authentication Methods

Method 1: Automatic OAuth (Recommended)

Method 2: API Key

Method 3: System gcloud

Logout

MCP Integration

Configure Your Agent

Virtual Tools for Agents

build_site

get_screen_code

get_screen_image

Key Commands

Exploration & Browsing

View Projects

View Specific Project

View Specific Screen

Browse Screens in Terminal

Tool Invocation

List All Available Tools

Show Tool Schema

Invoke a Tool

Development Workflow

Serve Project Locally

Generate Astro Site

Save Screen Snapshot

MCP Proxy

Environment Variables

Common Patterns

Pattern 1: Preview All Designs Before Building

Pattern 2: Agent-Driven Site Generation

Pattern 3: Iterative Design Review

Pattern 4: Automated Site Builds in CI

Troubleshooting

"Permission Denied" Errors

Authentication URL Not Appearing

"Already Authenticated" Issues

API Connection Fails After Setup

WSL / SSH / Docker Environments

MCP Proxy Not Responding

Tool Invocation Failures

Development & Testing

Real-World Agent Prompts

Example 1: Site Generation

Example 2: Design Review

Example 3: Batch Export

License

`build_site`

`get_screen_code`

`get_screen_image`