---
title: "Connect Zeplin to Claude: Review Screens, Annotations, and Notes"
slug: connect-zeplin-to-claude-review-screens-annotations-and-notes
date: 2026-06-09
author: Uday Gajavalli
categories: ["AI & Agents"]
excerpt: "Learn how to connect Zeplin to Claude using a managed MCP server. Review screens, read annotations, and extract design tokens using natural language."
tldr: "Connect Zeplin to Claude via Truto's managed MCP server to automate design handoffs. This guide covers bypassing Zeplin API complexities, generating secure tool endpoints, and extracting design tokens, screens, and notes using AI agents."
canonical: https://truto.one/blog/connect-zeplin-to-claude-review-screens-annotations-and-notes/
---

# Connect Zeplin to Claude: Review Screens, Annotations, and Notes


If you need to connect Zeplin to Claude to automate design handoffs, extract design tokens, or manage screen annotations, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's tool calls and Zeplin's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a [secure, authenticated MCP server URL](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/). If your team uses ChatGPT, check out our guide on [connecting Zeplin to ChatGPT](https://truto.one/connect-zeplin-to-chatgpt-manage-design-tokens-and-styleguide-assets/) or explore our broader architectural overview on [connecting Zeplin to AI Agents](https://truto.one/connect-zeplin-to-ai-agents-automate-workspace-and-design-delivery/).

Design handoff is a notoriously fragmented process. Product managers leave comments in Jira, designers update screens in Zeplin, and developers hunt for updated Hex codes and spacing variables. Giving a Large Language Model (LLM) read and write access to your Zeplin workspace bridges this gap, allowing AI to audit design consistency, summarize feedback, and generate front-end code directly from source-of-truth design tokens. 

However, exposing Zeplin's API to an LLM is a complex engineering challenge. You must handle authentication lifecycles, map deeply nested relational data schemas to MCP tool definitions, and manage strict rate limits. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Zeplin, connect it natively to Claude Desktop, and execute complex design workflows using natural language.

## The Engineering Reality of the Zeplin API

A custom MCP server is a self-hosted integration layer. While the [open MCP standard](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/) provides a predictable way for models to discover tools, the reality of implementing it against vendor APIs is painful. If you decide to [build a custom MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) for Zeplin, you own the entire integration lifecycle. Here are the specific challenges you will face:

**Deeply Nested Relational Graphs**
Zeplin's API is heavily hierarchical. To read a single comment on a design, you cannot simply query an endpoint. The resource path requires a project ID, a screen ID, and a note ID. To give Claude the ability to interact with a specific piece of feedback, your MCP server must expose multiple sequential tools so the LLM can navigate down the tree: `Organization -> Project -> Screen -> Note -> Comment`. If your tool schemas do not explicitly link these required parameters, the LLM will hallucinate IDs and fail.

**Complex Design Token Payloads**
Extracting design tokens - like colors, text styles, and spacing - involves parsing complex, highly specific JSON structures. A text style in Zeplin does not just return a CSS string; it returns an array of typography metrics including `font_family`, `font_size`, `font_weight`, `line_height`, and `font_stretch`. When building a custom MCP server, you have to map these verbose schemas perfectly so Claude understands which fields correspond to standard CSS or Tailwind values.

**Strict Rate Limits and Pagination**
Zeplin enforces rate limits on its endpoints. If your AI agent gets stuck in a loop attempting to summarize annotations across 50 screens, Zeplin will reject the requests with an HTTP `429 Too Many Requests`. 

It is a critical architectural decision *where* to handle these rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors automatically. Instead, when the upstream Zeplin API returns a `429`, Truto passes that error directly to the caller (Claude). Crucially, Truto normalizes the upstream rate limit information into standardized IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). This pass-through design ensures that your LLM framework or agent orchestrator is fully aware of the throttle state and can apply its own intelligent backoff, preventing the integration layer from silently hanging or consuming memory.

Instead of building this infrastructure from scratch, you can use Truto to expose Zeplin's endpoints as ready-to-use MCP tools.

## How to Generate a Zeplin MCP Server with Truto

Truto dynamically generates MCP tools based on Zeplin's actual API resources and documentation. There are two ways to generate your secure MCP server URL: via the Truto UI, or programmatically via the API.

### Method 1: Generating via the Truto UI

For one-off analysis tasks or local Claude Desktop usage, the UI is the fastest path.

1. Navigate to the integrated account page for your connected Zeplin instance in the Truto dashboard.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Select your desired configuration. You can restrict the server to specific HTTP methods (like `read` only) or specific tool tags.
5. Copy the generated MCP server URL (e.g., `https://api.truto.one/mcp/a1b2c3d4e5f6...`).

### Method 2: Generating via the API

If you are provisioning AI workspaces dynamically for your internal team, you should generate the MCP server programmatically. Make a `POST` request to the `/integrated-account/:id/mcp` endpoint.

```bash
curl -X POST https://api.truto.one/admin/integrated-accounts/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zeplin Design Ops Server",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'
```

The API returns a secure, hashed token URL. This URL encapsulates the authentication state for that specific Zeplin workspace.

```json
{
  "id": "mcp_srv_98765",
  "name": "Zeplin Design Ops Server",
  "url": "https://api.truto.one/mcp/xyz987...",
  "expires_at": "2026-12-31T23:59:59Z"
}
```

## Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with Claude. You can do this through the application interface or by modifying the underlying configuration file.

### Method A: Via the Application UI

For web-based AI interfaces or native apps with integration menus (like the upcoming Claude Web integrations or ChatGPT):

1. Open your LLM client's settings menu.
2. Navigate to **Integrations** or **Connectors** -> **Add MCP Server**.
3. Paste the Truto MCP URL.
4. Click **Connect**. The client will send an `initialize` request to the URL, discover the available tools, and make them immediately available in your chat context.

### Method B: Via the Configuration File (Claude Desktop)

For Claude Desktop, you register the server by editing the `claude_desktop_config.json` file. Because Truto MCP servers operate over standard HTTP, you use the official SSE (Server-Sent Events) transport wrapper provided by the Model Context Protocol SDK.

Open your configuration file (located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add the following:

```json
{
  "mcpServers": {
    "zeplin-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/xyz987..."
      ]
    }
  }
}
```

Restart Claude Desktop. A new "plug" icon will appear in the UI, indicating that your Zeplin tools are loaded and ready to use.

## Hero Tools for Zeplin Operations

Truto exposes dozens of Zeplin endpoints as tools. Here are the highest-leverage operations for design and front-end automation.

### list_all_zeplin_projects

Before Claude can fetch screens or design tokens, it needs context. This tool lists all projects the authenticated user has access to, returning critical IDs, platform targets (Web, iOS, Android), and resource counts.

**Contextual Usage:** Always the first step in a Zeplin workflow. The model uses this to map a human-readable project name (e.g., "Marketing Site Redesign") to a Zeplin `project_id`.

> "List all my Zeplin projects and find the ID for the 'Dashboard V2' project. Then, tell me how many screens and components are in it."

### list_all_zeplin_project_screens

Retrieves the metadata for every screen in a project, including names, descriptions, tags, and image thumbnail URLs. It also returns counts for notes, versions, and annotations.

**Contextual Usage:** Used to locate specific interfaces for review. If a developer asks for the "Checkout Page", Claude uses this tool to find the corresponding `screen_id`.

> "Get all screens for the Dashboard project. Identify any screen tagged with 'needs-review' and list their names and screen IDs."

### list_all_zeplin_project_design_tokens

Fetches the foundational design variables - colors (with RGBA values), spacing tokens, and text styles (with font family, line height, and size metrics) - from a project's local styleguide.

**Contextual Usage:** Essential for automated code generation. Claude can pull these tokens and instantly format them into CSS variables, SCSS mixins, or a Tailwind configuration object.

> "Extract all design tokens for the project. Output the colors and spacing tokens as a valid tailwind.config.js extension theme object."

### list_all_zeplin_screen_notes

Retrieves all conversational notes on a specific screen. Returns the note's status, color, position coordinates, and the full thread of comments including author details and content.

**Contextual Usage:** Perfect for PMs auditing feedback or developers checking if a design is approved for implementation.

> "Read all notes on the 'User Profile' screen. Summarize any unresolved comments regarding the placement of the 'Delete Account' button."

### create_a_zeplin_screen_annotation

Allows Claude to write back to Zeplin, placing a new annotation or note directly onto a screen layout.

**Contextual Usage:** Enables AI-driven design reviews. You can upload a screenshot of an implemented UI to Claude, have it compare the image against Zeplin's design tokens, and automatically leave annotations in Zeplin highlighting implementation discrepancies.

> "I am noticing a contrast issue on the header text. Create a red annotation on the 'Homepage' screen at coordinates x: 120, y: 45 with the note: 'Contrast ratio fails WCAG AA, please update the hex value.'"

### list_all_zeplin_project_components

Lists all reusable UI components within a project, including their variant properties, section details, and image URLs.

**Contextual Usage:** Used by developers to understand the component architecture before writing React or Vue components. Claude can map Zeplin variant properties directly to React props.

> "Fetch the components for this project. Find the 'Primary Button' component and list all its available variant properties."

### list_all_zeplin_styleguide_colors

If your organization uses global Styleguides rather than local project variables, this tool retrieves all standardized colors across your entire workspace.

**Contextual Usage:** Used to enforce brand consistency. Claude can audit a project's local colors against the global styleguide colors to ensure developers aren't using rogue hex codes.

> "Pull the colors from the core engineering styleguide and generate a CSS variable file named variables.css."

*For the complete tool inventory and detailed schema definitions, visit the [Zeplin integration page](https://truto.one/integrations/detail/zeplin).*

## Workflows in Action

Connecting Claude to Zeplin unlocks powerful cross-functional workflows. By chaining these tools, Claude acts as a bridge between design files and operational output.

### Workflow 1: Front-End Developer Scaffolding Tailwind Configs

Developers frequently waste time copying and pasting hex codes from design files into their codebases. Claude can automate this entirely.

> "I am setting up a new Next.js project. Look up the 'Enterprise Web App' project in Zeplin, extract all its design tokens, and generate a complete tailwind.config.ts file utilizing the project's exact spacing scale and color palette."

**Step-by-step execution:**
1. Claude calls `list_all_zeplin_projects` to find the ID for "Enterprise Web App".
2. Claude calls `list_all_zeplin_project_design_tokens` using that project ID to extract the raw typography, colors, and spacing metrics.
3. Claude parses the raw RGBA and pixel values from the Zeplin schema, translates them into standard CSS/Tailwind nomenclature, and outputs the formatted TypeScript code directly in the chat.

### Workflow 2: Product Manager Auditing Design Feedback

Before a sprint planning meeting, PMs need to know which screens are ready for development and which are blocked by open feedback.

> "Audit the 'Checkout Flow Redesign' project. Find all screens that have open notes. For each screen, summarize the unresolved feedback so I can present it in today's standup."

**Step-by-step execution:**
1. Claude calls `list_all_zeplin_projects` to locate the project.
2. Claude calls `list_all_zeplin_project_screens` to get a list of all screens and their metadata (which includes a `number_of_notes` property).
3. For every screen with notes, Claude iteratively calls `list_all_zeplin_screen_notes` to fetch the comment threads.
4. Claude synthesizes the data, filtering out resolved notes, and outputs a clean, bulleted summary of blockers organized by screen name.

## Security and Access Control

Giving an AI agent access to your intellectual property requires strict boundary management. Truto MCP servers support multiple layers of programmatic access control:

*   **Method Filtering (`config.methods`):** You can lock the server down to specific operations. Setting `methods: ["read"]` ensures the LLM can fetch screens and read notes, but physically cannot invoke tools like `create_a_zeplin_screen_annotation` or `update_a_zeplin_project_screen_by_id`.
*   **Tag Filtering (`config.tags`):** Limit the scope of available tools based on functional tags. You can restrict a server to only expose tools related to `design_tokens` or `comments`, hiding administrative endpoints like webhook management.
*   **Secondary Authentication (`require_api_token_auth`):** By default, the Truto MCP URL acts as a bearer token. By enabling this flag, the client must also pass a valid Truto API token in the `Authorization` header, ensuring that even if the URL leaks, it cannot be used by unauthenticated actors.
*   **Automatic Expiration (`expires_at`):** You can generate ephemeral servers. By setting an ISO timestamp, the server will automatically self-destruct - tearing down the Cloudflare KV entries and invalidating the token - perfect for giving a contractor temporary AI access to a specific Zeplin project.

## Elevating Design Operations with AI

The gap between design and code is fundamentally a data translation problem. Zeplin structures the data, but it still requires human effort to move that data into codebases, issue trackers, and standup notes. 

By leveraging an MCP server to connect Claude directly to Zeplin's APIs, you remove the manual translation layer. Developers get accurate tokens instantly, PMs get automated status reports, and teams stop wasting hours reconciling Hex codes. Using a managed layer like Truto means you get this capability immediately, without writing the boilerplate necessary to tame OAuth, schema parsing, and complex vendor rate limits.

> Stop building custom API integrations. Let Truto handle the boilerplate so your engineering team can focus on core product features.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)