stitch-mcp: getting AI-generated designs out of Stitch and into a repo

The problem is that designs live behind an API

stitch-mcp is a CLI for moving AI-generated UI designs into your development workflow, so you can preview them locally, build sites from them and feed them to coding agents.

The Why section explains the shape of the problem. AI-generated designs in Google's Stitch platform live as HTML and 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, and the tool handles that through a set of CLI commands that connect to Stitch.

The features list names six things. Preview designs locally by serving all screens from a project on a Vite dev server, build an Astro site from your designs by mapping screens to routes and generating a deployable project, and explore your design data by browsing projects, screens and metadata in the terminal or via the CLI.

Others are about the agent and the setup: give your agent design context by proxying Stitch tools to your IDE's coding agent with automatic token refresh, browse projects in your terminal with copy, preview and open actions, and set up in one command with a guided wizard that handles gcloud, auth and MCP client configuration.

The licence is Apache 2.0, the primary language is TypeScript, and the last push to the main branch was on 2026-05-28. The only release tag is v0.5.1 from 2026-03-22, while the package manifest says version 0.9.0, so the published package and the tag history have drifted apart.

The quick start, in three commands

The quick start covers the three things you would do in order, and each one is a single npx invocation.

# 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>

The init step is the guided one. Run it and follow the wizard, which handles gcloud installation, OAuth, credentials and project setup. The doctor command then verifies configuration health, and logout revokes credentials.

The serve step is the one you use most. It puts all the screens of a project on a Vite dev server, so you can see the designs as they will look rather than as a screenshot. The site step is the one that produces something you can ship, because it maps screens to routes and generates a deployable project, and the Astro compiler is a direct dependency of the package rather than something bolted on later.

There is also a snapshot command that saves screen state to a file, which is the one to reach for when you want to freeze a design before you start changing it.

For installation you do not need to install anything, since npx runs the package directly, or you can install it globally with npm install -g @_davideast/stitch-mcp, which gives you a stitch-mcp command.

The MCP proxy, and the three virtual tools

The integration story is the reason the project is called stitch-mcp rather than something else. You add a server entry to your MCP client config:

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

The supported clients are named: VS Code, Cursor, Claude Code, Gemini CLI, Codex and OpenCode. The proxy runs the MCP server and forwards to the upstream Stitch tools, with automatic token refresh so the agent does not stop working when a credential expires.

On top of the upstream tools, the proxy exposes three virtual tools, and the description says 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 and returns the design HTML for each page. get_screen_code retrieves a screen and downloads its HTML code content. And get_screen_image retrieves a screen and downloads its screenshot image as base64.

The build_site schema is the interesting one, because it is the contract an agent has to satisfy:

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

So a project id and a list of screen-to-route mappings. The same call works from the shell, through the tool command:

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

Exploring designs in the terminal before you prompt an agent

The README is explicit that you should use view and tool to browse your design data and understand what is available before prompting agents, and the reasoning is practical: an agent asked to build a page it cannot see will invent one.

# 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]

The view browser is an interactive terminal interface with a small key set. c copies the selected value, s previews the HTML in your browser, o opens the project in Stitch itself, and q quits. Arrow keys move between items and Enter drills into nested data.

The tool command is the escape hatch for the same operations the agent gets. Run it without a name to list all available tools, or with -s to see a tool's schema. So you can read the input schema of a virtual tool before you write it into a prompt, which is the difference between a tool call that works and one that fails on a missing required field.

The screens command, screens -p <id>, is a simpler variant that browses the screens of one project in the terminal, and the interactive browser is the fuller version of the same idea.

The command table groups the whole surface into four areas. Setup holds init, doctor and logout. Development holds serve, screens and view. Build holds site and snapshot. And Integration holds tool and proxy.

Authentication, and the environment that does not have a browser

There are three ways to authenticate, and the README marks the wizard as the recommended route.

The automatic path is to run init and follow the wizard, which handles gcloud installation, OAuth, credentials and project setup. The API key path sets the STITCH_API_KEY environment variable to skip OAuth entirely. And the manual path is for someone who already has gcloud configured:

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

With the manual path you then run the proxy with STITCH_USE_SYSTEM_GCLOUD=1, which is an env block in the MCP client config.

The environment variable table is the full list: STITCH_API_KEY for direct authentication, STITCH_ACCESS_TOKEN for a pre-existing access token, STITCH_USE_SYSTEM_GCLOUD to use system gcloud config instead of an isolated one, STITCH_PROJECT_ID and GOOGLE_CLOUD_PROJECT as project id overrides, and STITCH_HOST for a custom Stitch API endpoint.

The troubleshooting section has the entry that will matter most to anyone running this over SSH or in a container. The CLI detects WSL, SSH sessions, Docker containers and Cloud Shell, and in those environments browser-based auth may not work automatically, so you copy the OAuth URL from your terminal and open it in a browser manually. The related symptom is that the authentication URL does not appear at all, which the README explains as a five-second timeout while the tool prints the URL, and you look for one starting with https://accounts.google.com.

The Permission Denied case has its own checklist: you need the Owner or Editor role, billing enabled and the Stitch API enabled, and doctor --verbose diagnoses it.

Editorial conclusion

Adopt stitch-mcp if you design in Google's Stitch platform and need the result as code rather than as images, because the tool fetches the underlying HTML and CSS, serves it for preview, generates an Astro project and exposes the same operations to an agent through MCP. Do not adopt it expecting a polished product, because the README labels it an independent experimental tool, and note the version mismatch, where the published package is 0.9.0 while the latest release tag is v0.5.1. Before you start, pick your authentication route, since the wizard handles gcloud and OAuth but an API key skips that entirely, and check that the Stitch API is enabled and billing is on, which is the first thing the doctor command diagnoses.

Frequently asked questions

Official sources

1. davideast/stitch-mcp on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases