# Stitch-MCP

An MCP (Model Context Protocol) server that exposes Google Stitch capabilities as local tools by forwarding requests to the remote Stitch MCP endpoint.

## What this does

This server:

- Runs a local MCP tool server (stdio) using `mcp.server.fastmcp.FastMCP`
- Forwards tool calls to `https://stitch.googleapis.com/mcp`
- Requires a Stitch API key provided via the `STITCH_API_KEY` environment variable

## Requirements

- Python 3.11+
- A Stitch API key (`STITCH_API_KEY`)

## Installation

Create and activate a virtual environment, then install the package:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configuration

The server loads environment variables from a local `.env` file (via `python-dotenv`) if present.

Create a `.env` file:

```bash
STITCH_API_KEY=your_api_key_here
```

## Run the server

You can run it via the installed script:

```bash
stitch-mcp
```

Or directly:

```bash
python server.py
```

In your MCP client, register a stdio server that runs `stitch-mcp` (or `python server.py`) and ensure `STITCH_API_KEY` is available in that process environment.

## Available tools

Project management:

- `list_projects(filter: Optional[str] = None)`
- `create_project(title: str)`
- `get_project(name: str)`

Screen management:

- `list_screens(projectId: str)`
- `get_screen(name: str, projectId: str, screenId: str)`

AI generation:

- `generate_screen_from_text(projectId: str, prompt: str, deviceType: str = "MOBILE", modelId: str = "GEMINI_3_FLASH")`
- `edit_screens(projectId: str, selectedScreenIds: list[str], prompt: str, deviceType: str = "DEVICE_TYPE_UNSPECIFIED", modelId: str = "GEMINI_3_FLASH")`
- `generate_variants(projectId: str, selectedScreenIds: list[str], prompt: str, variantCount: int = 3, creativeRange: str = "EXPLORE", aspects: Optional[list[str]] = None, deviceType: str = "DEVICE_TYPE_UNSPECIFIED", modelId: str = "GEMINI_3_FLASH")`

Design systems:

- `list_design_systems(projectId: Optional[str] = None)`
- `create_design_system(...)`
- `update_design_system(...)`
- `apply_design_system(projectId: str, assetId: str, screen_instance_ids: list[str], screen_source_names: list[str])`

## Notes and troubleshooting

- If you see `STITCH_API_KEY environment variable not set`, verify your `.env`/environment and restart the MCP client process.
- Some generation operations can take a few minutes. If a request times out, wait and call `get_screen` later (the server returns a timeout message in this case).

## Development

`agent.py` is a small helper script for manually exercising the tools without an MCP client. Update the placeholder IDs and run:

```bash
python agent.py
```

## Contribution

- If you have any suggestions to this Project or about the Script, feel free to inform me. And if you liked, you are free to use it for yourself.(P.S. Star it too!! 😬 )

- Your Contributions are much welcomed here!
   > Fork the project
   > > Compile your work
   > > > Call in for a Pull Request

Credits: [Samuel Jayasingh](https://github.com/SamuelJayasingh)

Last Edited on: 16/04/2026