Content
# 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
```bash
# 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:
```json
{
"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:
```json
{
"projectId": "string (required)",
"routes": [
{
"screenId": "string (required)",
"route": "string (required, e.g. \"/\" or \"/about\")"
}
]
}
```
Example:
```bash
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.
```bash
# 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):
```bash
npx @_davideast/stitch-mcp <command>
```
Or install globally:
```bash
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.
```bash
npx @_davideast/stitch-mcp init
```
**API key:** Set the `STITCH_API_KEY` environment variable to skip OAuth entirely.
```bash
export STITCH_API_KEY="your-api-key"
```
**Manual (existing gcloud):** If you already have gcloud configured:
```bash
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`:
```json
{
"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:
```bash
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:
```bash
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
```bash
# 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.**
