--- name: stitch-mcp-a001d759bff3 description: >- Connects a coding agent to Google Stitch through the stitch-mcp CLI and MCP proxy, so the agent can read a screen's HTML and screenshot and rebuild it in the project's own framework. Use when a user says "implement this Stitch screen", "hook Stitch up to Claude Code / Cursor / Codex", "add the Stitch MCP server", "turn my Stitch project into a site", "preview my Stitch screens locally", or when Stitch tools fail with authentication or permission errors. Covers choosing API key or OAuth, proxy or direct HTTP, per-client configuration, the non-interactive flags an agent can run, the tool inputs and outputs, and how to diagnose a broken setup. license: Apache-2.0 compatibility: "Node.js 18+ with npx; a Google Stitch account and either a Stitch API key or a Google Cloud project; any MCP client" metadata: author: terminal-skills version: "2.0.0" category: design tags: "stitch, mcp, design-to-code, google, ui" repository: https://github.com/davideast/stitch-mcp --- # Stitch MCP ## Overview Google Stitch generates UI screens from prompts and stores each one as an HTML document plus a screenshot. `stitch-mcp` (npm package `@_davideast/stitch-mcp`, an independent open-source project) is the bridge to a codebase. It does three jobs: it registers Stitch as an MCP server in a coding agent, it adds helper tools that hand the agent a screen's markup in a single call, and it can preview screens or export them as an Astro project. Facts below were checked against version 0.9.0; run any command with `--help` if a flag is rejected. The agent's real work starts after the fetch: Stitch output is one static HTML page per screen, and the job is to translate it into components that fit the repository it lands in. ## Instructions ### 1. Establish the starting point Ask or look up, in this order: - Which MCP client is in use (Claude Code, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Antigravity) and whether a `stitch` server is already registered. - Whether the user has a Stitch API key. Without one the setup goes through Google Cloud OAuth, which needs a browser and a billing-enabled project. - The Stitch project and the screens to implement. A project ID is a long number such as `7302915846120394175`; a screen ID is 32 hex characters. Display names are not accepted. - The target stack, read from the repository: framework, styling system, existing components and design tokens. Never assume React and Tailwind. ### 2. Choose authentication | Mode | How it is supplied | Choose it when | |------|--------------------|----------------| | API key | `STITCH_API_KEY` in the environment, a `.env` file, or the MCP server's `env` block | Default. Works headless, in CI and over SSH; nothing to refresh | | OAuth via the wizard | `init` downloads its own gcloud SDK into `~/.stitch-mcp/` and signs in | The user has no key but owns a Google Cloud project | | OAuth via existing gcloud | `STITCH_USE_SYSTEM_GCLOUD=1` plus the three commands below | gcloud is already installed and signed in | Existing-gcloud route, to be run by the user because it opens a browser: ```bash gcloud auth application-default login gcloud config set project orchard-design-prod gcloud beta services mcp enable stitch.googleapis.com --project=orchard-design-prod ``` With no key present the CLI assumes OAuth. In a check run, `doctor` on a clean machine fetched roughly 500 MB of gcloud SDK into `~/.stitch-mcp/` before reporting anything, so export the key first when the key route is intended. ### 3. Choose the connection | | Proxy over stdio | Direct HTTP | |---|---|---| | What the client starts | `npx @_davideast/stitch-mcp proxy` as a child process | Nothing; it calls `https://stitch.googleapis.com/mcp` | | Tools the agent sees | Stitch's own tools plus the four helpers in step 6 | Stitch's own tools only | | OAuth token lifetime | Renewed for you by the proxy | One hour, then replaced by hand | | Fits | Interactive design-to-code sessions | Pipelines and sandboxes that cannot spawn processes | Pick the proxy unless there is a concrete reason not to: without `get_screen_code` the agent must call `get_screen`, find the download URL and fetch the markup itself. ### 4. Register the server Claude Code, proxy with an API key taken from the shell environment: ```bash claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy ``` Claude Code, direct HTTP (`-s user` writes to `~/.claude.json`, `-s project` to `./.mcp.json`): ```bash claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \ --header "X-Goog-Api-Key: $STITCH_API_KEY" -s user ``` Cursor (`.cursor/mcp.json`) and Antigravity share one shape. This variant uses OAuth, so the file carries no secret and is safe to commit: ```json { "mcpServers": { "stitch": { "command": "npx", "args": ["@_davideast/stitch-mcp", "proxy"], "env": { "STITCH_PROJECT_ID": "orchard-design-prod" } } } } ``` For the API-key route the `env` block holds `STITCH_API_KEY` instead; keep that file out of version control or use the client's own environment interpolation. Differences in other clients: - VS Code (`.vscode/mcp.json`): the top-level key is `servers`, and each entry needs `"type": "stdio"` (or `"type": "http"` with `url` and `headers`). - Codex (`~/.codex/config.toml`): a `[mcp_servers.stitch]` table with `command = "npx"` and `args = ["@_davideast/stitch-mcp", "proxy"]`; variables go under `[mcp_servers.stitch.env]`. - OpenCode (`opencode.json`): `"mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }`. - Antigravity, direct mode only: the field is `serverUrl`, not `url`. - Gemini CLI: `gemini extensions install https://github.com/gemini-cli-extensions/stitch`. `npx @_davideast/stitch-mcp init` writes the same configuration through prompts. It accepts `-c, --client` (`claude-code`, `cursor`, `vscode`, `codex`, `opencode`, `gemini-cli`, `antigravity`) and `-t, --transport` (`stdio` or `http`) to skip two of them, but it remains a wizard: hand it to the user instead of running it from an agent shell. Restart the client after any change to its MCP configuration. ### 5. Verify before relying on it ```bash npx @_davideast/stitch-mcp doctor --verbose # add --json for machine-readable results npx @_davideast/stitch-mcp tool # lists every tool the CLI can reach ``` `doctor` checks, depending on the mode: key present, key accepted by the API, gcloud at 400.0.0 or newer, user signed in, application default credentials, active project, API reachable. If the `tool` listing includes `build_site`, the helper tools are available. ### 6. Find the screens and fetch them Several commands open a terminal UI and will hang in an agent shell: `init`, `screens`, `view`, and `site` without `--routes` or one of its JSON flags. Use these instead: ```bash npx @_davideast/stitch-mcp tool list_projects -o json npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens npx @_davideast/stitch-mcp tool get_screen_code -o json \ -d '{"projectId":"7302915846120394175","screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12"}' ``` `site --list-screens` prints `{ success, projectId, screens: [{ screenId, title, suggestedRoute, hasHtml }] }`. A screen with `hasHtml: false` has no markup to fetch yet. | Tool | Source | Input | What comes back | |------|--------|-------|-----------------| | `list_projects`, `get_project` | Stitch | none / `name` (`projects/ID`) | Projects the account can open | | `list_screens`, `get_screen` | Stitch | `projectId` / `name` (`projects/ID/screens/SCREEN_ID`) | Metadata and download URLs, not markup | | `generate_screen_from_text`, `edit_screens`, `generate_variants` | Stitch | prompt-driven | New or changed screens in the project | | `get_screen_code` | proxy | `projectId`, `screenId` | `{ screenId, projectId, htmlContent }` | | `get_screen_image` | proxy | `projectId`, `screenId` | `{ screenId, projectId, imageContent }`, the screenshot as base64 | | `build_site` | proxy | `projectId`, `routes[]` of `{ screenId, route }` | `{ success, pages: [{ screenId, route, title, html }], message }` | | `list_tools` | proxy | none | Names, descriptions and input schemas | `tool NAME -s` prints the input schema of any tool. `-f, --data-file` reads the JSON body from a file, and `-o` takes `json`, `pretty` (default) or `raw`. ### 7. Turn the markup into project code 1. Fetch `get_screen_code` and `get_screen_image` for each screen. The HTML carries exact colours, spacing and font stacks; the image shows what the result should look like. 2. Inventory what repeats across screens (navigation, footer, buttons, cards) before writing any file, and map each to an existing component or a new shared one. 3. Map raw values onto the project's tokens. A hex colour that matches a theme variable becomes the variable; a one-off value stays literal and is listed in the hand-off note. 4. Rebuild the structure with semantic elements, real links and form controls, and the project's data layer in place of hard-coded sample content. 5. Compare the running page with the screenshot at the design's width, then at a phone width, and report every deliberate deviation. The generating tools, `create_project`, `delete_project` and the design-system tools change the user's Stitch account. Call them only when the user asks for that, never as a side effect of implementing a design. ### 8. Preview or export without an agent | Command | Purpose | Flags worth knowing | |---------|---------|---------------------| | `serve -p ID` | Local Vite server, one URL per screen under `/screens/` | `--list-screens` prints paths as JSON; `--json` starts headless and prints JSON once the server is ready | | `site -p ID` | Writes an Astro project from a screen-to-route map | `-o DIR` output folder; `-r JSON` supplies the map and skips the UI; `-e` prints the map as `build_site` input | | `upload -p ID -f FILE` | Adds a PNG, JPG, WEBP or HTML file as a new screen | `--title` | | `proxy` | The MCP server itself | `--debug` logs to `/tmp/stitch-proxy-debug.log` | | `logout` | Revokes the OAuth sign-in | `--force`, `--clear-config` (asks the user first: it deletes the bundled gcloud configuration) | The Astro output contains `src/layouts/Layout.astro`, one file per route in `src/pages/`, and downloaded assets in `public/assets/`; it starts with `npm install && npm run dev` on port 4321. ## Examples ### Example 1: Implement one Stitch screen in an existing Next.js app Ilse Brandt maintains a booking app (Next.js App Router, Tailwind with tokens in `tailwind.config.ts`). She uses Claude Code, has a Stitch API key in her shell profile, and asks: "implement the Pricing screen from my Stitch project." ```bash claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens ``` The listing shows `{"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing", "suggestedRoute":"/pricing","hasHtml":true}`. After a client restart the agent calls `get_screen_code` and `get_screen_image` with those IDs, then reports: ```text Screen: Pricing (c41f0a9e…5a12) -> app/pricing/page.tsx Reused: components/SiteHeader.tsx, components/Button.tsx (variant "primary") Created: components/pricing/PlanCard.tsx, components/pricing/BillingToggle.tsx Tokens: #1F6F5C -> colors.brand.600; 24px card gap -> gap-6; 44px heading kept as text-[44px] Changed on purpose: plan prices read from lib/plans.ts instead of the sample figures Checked: 1440px and 390px against the screenshot; toggle is keyboard-operable ``` ### Example 2: Export three screens as an Astro site from a headless shell Tomasz Wrona works over SSH on a build host and wants a static marketing site from a Stitch project with no terminal UI involved. The key is already exported in the session. ```bash npx @_davideast/stitch-mcp site -p 5518204776390142068 --list-screens > screens.json npx @_davideast/stitch-mcp site -p 5518204776390142068 -o ./harbour-site -r '[ {"screenId":"0b7e3c915ad84f2e9c6d1a8f4e2b7c30","route":"/"}, {"screenId":"9a2d6f1c4b8e47a3b5c0e7d19f3a6b48","route":"/services"}, {"screenId":"e5c81b07d3f24a69a1b4c92d6e0f7a15","route":"/contact"} ]' cd harbour-site && npm install && npm run build ``` Result: `src/pages/index.astro`, `services.astro` and `contact.astro` wrapped in the shared layout, with images and fonts under `public/assets/`. The agent then replaces the duplicated header and footer markup in the three pages with one Astro component each, and notes that two routes may not share a path and that an unknown screen ID aborts the build with the missing IDs listed. ## Guidelines - A "Permission Denied" response under OAuth usually means one of three things: billing is off, the Stitch API is not enabled on the project, or the account lacks the Owner or Editor role. `doctor --verbose` shows the HTTP error. - Two gcloud installations are a common trap. The bundled one keeps credentials in `~/.stitch-mcp/config/`; signing in with the system gcloud does nothing for it unless `STITCH_USE_SYSTEM_GCLOUD=1` is set. - Other variables the CLI reads: `STITCH_ACCESS_TOKEN` (a token obtained elsewhere), `STITCH_PROJECT_ID` or `GOOGLE_CLOUD_PROJECT` (project override), `STITCH_HOST` (alternative endpoint). - On WSL, SSH and containers the OAuth link is printed instead of opened; the user copies it into a browser. An API key avoids the problem entirely. - `snapshot` renders the CLI's own terminal screens from a data file for its developers. It does not save or version Stitch designs; keep fetched HTML in the repository if a record is needed. - Treat fetched HTML as a design reference. Pasting it into a page verbatim brings inline styles, remote font and image URLs, and no accessibility work. - Pin the package (`@_davideast/stitch-mcp@0.9.0`) in shared configuration so every teammate and the CI run the same tool set; the project is experimental and not affiliated with Google. - For the visual polish pass after implementation, pair this with the `impeccable` and `frontend-design` skills. - Not the right tool when the design lives in Figma or as a static mock-up image, or when the user wants a design generated but not implemented: in the last case Stitch's web UI is enough. --- Source attribution: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/stitch-mcp/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to the Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by the Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding any notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS Copyright 2025 Terminal Skills Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Mega AI Hub resource metadata Creator / publisher: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/stitch-mcp/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Design Roles: Frontend Developer, Product Designer, UX Designer Specialties: Frontend, Design Tools: Stitch, Mcp Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: dab5ab7ae455c0224c83cad201ed14edf4d94cf50e999058c7a805d14acfd167