Stitch Mcp Auto

Stitch MCP Auto 🎨

[English](README.md) | [한국어](README.ko.md)

> One command. Instant UI. > The most automated MCP server for Google Stitch.

💡 Just share this link with your AI: https://github.com/GreenSheep01201/stitch-mcp-auto

---

Why stitch-mcp-auto?

| Feature | stitch-mcp | stitch-mcp-auto | |---------|------------|-----------------| | Setup time | ~30 min (manual) | ~2 min (wizard) | | gcloud config | Manual | Automatic | | MCP registration | Manual | Automatic | | Multi-CLI support | ❌ | ✅ Claude/Gemini/Codex | | AI image generation | ❌ | ✅ Gemini 3 Pro | | Custom commands | ❌ | ✅ 7 workflows |

---

Features:

• Auto Setup - One command installs everything (gcloud auth, API enable, MCP config)
• Multi-CLI Support - Works with Claude Code, Gemini CLI, Codex CLI
• 19 Custom Tools + Stitch Core - Design generation, accessibility checks, tokens, responsive variants, and design system export
• 7 Workflow Commands - /design, /design-system, /design-flow, /design-qa, /design-export, /generate-asset, /design-full
• 🎨 AI Image Generation - Generate logos, icons, hero images via Gemini 3 Pro (uses [Antigravity](#ai-image-generation-tools-v110) - Google's experimental image generation API)
• 🎭 Orchestration Mode - One prompt to generate assets + complete UI design
• 🌐 i18n Support - Auto-detects system language (English/Korean) for setup wizard and console messages

---

Table of Contents

• [Why stitch-mcp-auto?](#why-stitch-mcp-auto)
• [Prerequisites (Install These First)](#prerequisites-install-these-first)
• [1. Install Node.js (v18 or higher)](#1-install-nodejs-v18-or-higher)
• [2. Install Google Cloud CLI (gcloud)](#2-install-google-cloud-cli-gcloud)
• [Quick Start](#quick-start)
• [AI Agent Quick Start (Semi-Automated)](#ai-agent-quick-start-semi-automated)
• [Manual Installation (Alternative)](#manual-installation-alternative)
• [Step 1: Run Auto Setup](#step-1-run-auto-setup)
• [Step 3: Configure MCP Client](#step-3-configure-mcp-client)
• [Available Tools](#available-tools)
• [Automatic Project Management (NEW)](#automatic-project-management-new)
• [Core Stitch Tools (API + convenience wrappers)](#core-stitch-tools-api--convenience-wrappers)
• [Professional Web Design Tools](#professional-web-design-tools)
• [Design Consistency Tools](#design-consistency-tools)
• [Productivity Tools](#productivity-tools)
• [Quality & Analysis Tools](#quality--analysis-tools)
• [Design Enhancement Tools](#design-enhancement-tools)
• [AI Image Generation Tools (v1.1.0)](#ai-image-generation-tools-v110)
• [Supported Models for Image Generation](#supported-models-for-image-generation)
• [Background Removal (NEW)](#background-removal-new)
• [MCP Prompts (Auto-Discovered)](#mcp-prompts-auto-discovered)
• [Custom Commands (Multi-CLI Support)](#custom-commands-multi-cli-support)
• [Supported CLIs](#supported-clis)
• [Available Commands](#available-commands)
• [CLI Usage Examples](#cli-usage-examples)
• [Commands Installation Location](#commands-installation-location)
• [Usage Examples](#usage-examples)
• [Create a New Project](#create-a-new-project)
• [Generate a Screen](#generate-a-screen)
• [Generate with Specific Style](#generate-with-specific-style)
• [Multi-language Support](#multi-language-support)
• [The "Designer Flow"](#the-designer-flow)
• [Using Design Tokens](#using-design-tokens)
• [Trending Design Generation](#trending-design-generation)
• [Batch Screen Generation](#batch-screen-generation)
• [Accessibility Check](#accessibility-check)
• [Design System Export](#design-system-export)
• [AI Image Generation (NEW in v1.1.0)](#ai-image-generation-new-in-v110)
• [Full Design Orchestration (NEW in v1.1.0)](#full-design-orchestration-new-in-v110)
• [Troubleshooting](#troubleshooting)
• ["gcloud: command not found"](#gcloud-command-not-found)
• ["Stitch API has not been used in project" Error](#stitch-api-has-not-been-used-in-project-error)
• [Token Expired / Authentication Error](#token-expired--authentication-error)
• ["Connection Refused" After Google Login](#connection-refused-after-google-login)
• [Browser Doesn't Open Automatically (WSL)](#browser-doesnt-open-automatically-wsl)
• [Full Reset](#full-reset)
• [Architecture](#architecture)
• [File Structure](#file-structure)
• [Configuration Files](#configuration-files)
• [Scripts](#scripts)
• [Requirements](#requirements)
• [Security Note](#security-note)
• [License](#license)
• [Credits](#credits)
• [Support](#support)

---

Prerequisites (Install These First)

1. Install Node.js (v18 or higher)

Windows

# Using winget (Windows 10/11)
winget install OpenJS.NodeJS.LTS

# Or download installer from: https://nodejs.org/

macOS

# Using Homebrew
brew install node@22

# Or download installer from: https://nodejs.org/

Linux / WSL

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Or using apt (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify Node.js installation:

node --version   # Should show v18.x.x or higher
npm --version    # Should show 9.x.x or higher

---

2. Install Google Cloud CLI (gcloud)

Windows

Option A: Installer (Recommended)

1. Download from Google Cloud SDK
2. Run the installer (check "Run gcloud init" option)
3. Restart your terminal

Option B: PowerShell

(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:TEMP\gcloud.exe")
Start-Process "$env:TEMP\gcloud.exe" -Wait
# Restart terminal after installation

macOS

# Using Homebrew (Recommended)
brew install --cask google-cloud-sdk

# Or direct install
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

Linux / WSL

# Download and install
curl -sSL https://sdk.cloud.google.com | bash -s -- --disable-prompts --install-dir=$HOME

# Add to PATH
echo 'export PATH="$HOME/google-cloud-sdk/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify gcloud installation:

gcloud --version
# Should show: Google Cloud SDK xxx.x.x

---

Quick Start

After installing Node.js and gcloud CLI:

npx stitch-mcp-auto-setup

The setup wizard will:

1. Open a web-based setup page at http://localhost:51121
2. Guide you through Google login
3. Help you select or create a project
4. Enable the Stitch API
5. Save your configuration

> Note: When starting the MCP server directly (npx stitch-mcp-auto or via your editor), the setup wizard runs on http://localhost:8086.

> 🤖 AI Agent Note (WSL Environment): > If running in WSL, the browser cannot open automatically. Open the URL shown in the terminal (usually http://localhost:51121 for setup.js, or http://localhost:8086 when the MCP server starts) in your Windows browser: > ``powershell > # Run this in PowerShell (not WSL terminal) > Start-Process "http://localhost:51121" > # If you see 8086 instead: > Start-Process "http://localhost:8086" > `` > Or instruct the user to manually open the shown URL in their Windows browser.

---

AI Agent Quick Start (Semi-Automated)

This repo supports semi-automated setup with a few unavoidable manual steps (OAuth login).

Checklist (agent-friendly):

1. Run setup: npm run setup (or npx -p stitch-mcp-auto stitch-mcp-auto-setup)
2. Open the URL shown in terminal (usually http://localhost:51121)
3. Complete Google login in the browser (gcloud + Stitch API enable)
4. ⚠️ CRITICAL: Verify MCP registration (see below)
5. Start server: npm start or let the editor launch it

Manual-only steps:

• Browser OAuth consent (Google login)
• WSL browser opening (must open URL manually)

Environment-specific commands:

• Windows (PowerShell):
• Open setup URL: Start-Process "http://localhost:51121" (or http://localhost:8086)
• macOS:
• Open setup URL: open "http://localhost:51121" (or http://localhost:8086)
• Linux:
• Open setup URL: xdg-open "http://localhost:51121" (or http://localhost:8086)
• WSL (Windows host):
• Run in Windows PowerShell: Start-Process "http://localhost:51121"

⚠️ Post-Installation MCP Verification (REQUIRED)

After setup completes, always verify that the MCP server is registered:

# Claude Code
claude mcp list | grep stitch

# Gemini CLI
gemini mcp list | grep stitch

# Codex CLI
codex mcp list | grep stitch

If stitch is NOT listed, manually register:

| CLI | Manual Registration Command | |-----|----------------------------| | Claude Code | claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y stitch-mcp-auto | | Gemini CLI | gemini mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID | | Codex CLI | codex mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID |

> Why verification is needed: The setup wizard writes directly to config files (~/.claude.json, ~/.gemini/settings.json, ~/.codex/config.toml), but verification ensures the configuration is correct. Always verify to avoid "MCP server not found" errors.

Other Verification (optional):

• node auth.js --status (shows token + project status)
• npm start (server boots and prints "Ready")

---

Manual Installation (Alternative)

Step 1: Run Auto Setup

npx -p stitch-mcp-auto stitch-mcp-auto-setup

Or if you cloned the repository:

node setup.js

Setup Process

1. Welcome Page - Click "Login with Google" button
2. Google Login - A new browser window opens for authentication

• After login, you may see "Connection refused" page - just close it
• The setup page will automatically detect your login

1. Project Selection - Choose an existing project or create a new one
2. API Activation - Click the button to enable Stitch API

• Wait for activation (may take a few seconds)

1. Complete - Copy the MCP configuration to your editor

> ⚠️ WSL Users - IMPORTANT: > WSL cannot open browsers directly. When the setup wizard starts: > 1. Copy the URL http://localhost:51121 > 2. Open it manually in your Windows browser (Chrome, Edge, etc.) > 3. Or run in PowerShell: Start-Process "http://localhost:51121" > > The authentication will work because WSL shares localhost with Windows.

---

Step 3: Configure MCP Client

After setup completes, add the configuration to your MCP client.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["-y", "stitch-mcp-auto"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Claude Code

🌐 Method 1: CLI Command (Recommended)

The setup wizard automatically writes to ~/.claude.json. To add manually via CLI:

claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y stitch-mcp-auto

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["-y", "stitch-mcp-auto"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

📁 Method 2: Per-project Settings

Create .mcp.json in your project root:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["-y", "stitch-mcp-auto"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Gemini CLI

🌐 Method 1: CLI Command (Recommended)

gemini mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

Or edit ~/.gemini/settings.json directly:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["-y", "stitch-mcp-auto"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "YOUR_PROJECT_ID"
      }
    }
  }
}

Codex CLI

🌐 Method 1: CLI Command (Recommended)

codex mcp add stitch -- npx -y stitch-mcp-auto --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

Or edit ~/.codex/config.toml directly:

[mcp_servers.stitch]
command = "npx"
args = ["-y", "stitch-mcp-auto"]

[mcp_servers.stitch.env]
GOOGLE_CLOUD_PROJECT = "YOUR_PROJECT_ID"

Cursor

Go to Settings > MCP > Add New Server and add:

• Command: npx
• Args: -y stitch-mcp-auto
• Environment: GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

Optional: GOOGLE_CLOUD_PROJECT is only used for Stitch image fallback and auth.js --status. The setup wizard stores the active project in ~/.stitch-mcp-auto/config.json, and workspace tools save .stitch-project.json in your current folder.

---

Available Tools

🔄 Automatic Project Management (NEW)

No more manual projectId passing! The server automatically manages project context:

1. Auto-detection: When you call tools like generate_screen_from_text without projectId, it automatically uses the workspace project
2. Auto-save: When you create_project, it's automatically saved to .stitch-project.json in your current folder
3. Session continuity: Return to the same folder later, and your project is automatically loaded

How it works:

┌─────────────────────────────────────────────────────────────┐
│  Tool called without projectId                              │
│                      ↓                                      │
│  1. Check active session project                            │
│  2. If none → Load from .stitch-project.json                │
│  3. If none → Return "PROJECT_REQUIRED" with options        │
│                      ↓                                      │
│  User creates/selects project → Auto-saved to workspace     │
└─────────────────────────────────────────────────────────────┘

Manual workspace tools (optional):

| Tool | Description | |------|-------------| | get_workspace_project | 🔍 Check current workspace project status | | set_workspace_project | 💾 Manually associate a project with the workspace | | clear_workspace_project | 🗑️ Clear workspace project association |

Core Stitch Tools (API + convenience wrappers)

| Tool | Description | |------|-------------| | create_project | Creates a new Stitch project. A project is a container for UI designs and frontend code. | | get_project | Retrieves the details of a specific Stitch project using its project name. | | list_projects | Lists all Stitch projects accessible to the user. By default, it lists projects owned by the user. | | list_screens | Lists all screens within a given Stitch project. | | get_screen | Retrieves the details of a specific screen within a project. | | generate_screen_from_text | Generates a new screen within a project from a text prompt. | | fetch_screen_code | Retrieves the actual HTML/Code content of a screen. | | fetch_screen_image | Retrieves the screenshot/preview image of a screen. |

🎨 Professional Web Design Tools

Design Consistency Tools

| Tool | Description | |------|-------------| | extract_design_context | Extracts design DNA (colors, typography, spacing, components) from an existing screen for visual consistency across multiple screens. | | apply_design_context | Generates a new screen using a previously extracted design context to maintain visual consistency. | | compare_designs | Compares two screens to identify design differences, inconsistencies, and suggest harmonization. |

Productivity Tools

| Tool | Description | |------|-------------| |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GreenSheep01201
• Source: GreenSheep01201/stitch-mcp-auto
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.