# Table of Contents

- [Gemini Design MCP](#gemini-design-mcp)

---

# Gemini Design MCP

1

### Get your API Key

Create your API key from the dashboard. Free tier includes 10K tokens/month.

[Go to Dashboard](https://gemini-design-mcp.com/dashboard/api-keys)

2

### Configure your tool

AllAppCLIIDETerminal

Claude Code

CLI

LocalRemote

Runs locally on your machine. Requires Node.js >= 18.

Run in terminalCopy

    claude mcp add gemini-design-mcp --env API_KEY=your_api_key_here -- npx -y gemini-design-mcp@latest

Replace `your_api_key_here` with your actual API key.

3

### Add agent instructions

Add this to your `CLAUDE.md` or `AGENTS.md` file.

\# MCP Gemini Design - MANDATORY FOR FRONTEND
=============================================

\## ABSOLUTE RULE - NEVER IGNORE
--------------------------------

**You MUST NEVER write frontend/UI code yourself.**

Gemini is your frontend developer. You are NOT allowed to create visual components, pages, or interfaces without going through Gemini. This is NON-NEGOTIABLE.

### \### When to use Gemini? ALWAYS for:

*   Creating a page (dashboard, landing, settings, etc.)
*   Creating a visual component (card, modal, sidebar, form, button, etc.)
*   Modifying the design of an existing element
*   Anything related to styling/layout

### \### Exceptions (you can do it yourself):

*   Modifying text/copy
*   Adding JS logic without changing the UI
*   Non-visual bug fixes
*   Data wiring (useQuery, useMutation, etc.)

\## MANDATORY Workflow
----------------------

**1\. New project:** `generate_vibes` → user chooses → `create_frontend` with `generateDesignSystem: true`

**2\. Save design system:** Save `designSystem` to `design-system.md` at project root

**3\. Subsequent pages:** Pass `projectRoot` to auto-load design system

**4\. Existing project:** Pass CSS/theme files in `context`

\## Design System Feature
-------------------------

Set `generateDesignSystem: true` for the FIRST page. Gemini returns code + design system. Save to `design-system.md`. For subsequent calls, pass `projectRoot` for consistent styling.

\## WHAT IS FORBIDDEN
---------------------

*   Writing a React component with styling without Gemini
*   Creating a page without Gemini
*   "Reusing existing styles" as an excuse to not use Gemini
*   Doing frontend "quickly" yourself

\## WHAT IS EXPECTED
--------------------

*   Call Gemini BEFORE writing any frontend code
*   Ask user for vibe choice if new project
*   Use `generateDesignSystem: true` for FIRST page, save `design-system.md`
*   Pass `projectRoot` for subsequent calls
*   Let Gemini design, you implement

### You're ready!

Restart your agent and start asking for frontend work. Gemini will handle the design automatically.

### What is Remote Server?

Skip the local setup and connect directly to our cloud-hosted MCP server.

Remote Server mode lets you use Gemini Design MCP **without installing anything on your machine**. Instead of running the MCP server locally, your agent connects to our hosted server via the internet.

This is perfect for **quick testing**, **restricted environments**, or when you **don't want to manage Node.js dependencies**.

#### Local Mode

*   Runs entirely on your machine
*   Faster response times (no network latency)
*   Works offline once installed
*   Requires Node.js >= 18

#### Remote Server Mode

*   No installation required
*   Works on any system (no Node.js needed)
*   Always up-to-date (server updates automatically)
*   Requires internet connection

#### How to use Remote Server

1.  1
    
    Get your API key
    
    Create one from the [dashboard](https://gemini-design-mcp.com/dashboard/api-keys)
    .
    
2.  2
    
    Select "Remote" in the configuration above
    
    Toggle to Remote mode in Step 2 to get the right config.
    
3.  3
    
    Copy and paste the configuration
    
    Replace `your_api_key_here` with your actual key.
    

Technical note

Remote mode uses `mcp-remote` to proxy the connection to our server at `https://gemini-design-mcp-server-production.up.railway.app/mcp`. Your API key is sent via the Authorization header for authentication. The connection uses Server-Sent Events (SSE) for real-time communication.

### create\_frontend

Scaffolds complete responsive views from high-level requirements.

**Use when:** You need a completely new page or component from scratch.

**Input:** Natural language description of what you want, tech stack, file path.

**Output:** Complete, production-ready file with responsive design.

Example prompt

"Create a pricing page with 3 tiers (Basic, Pro, Enterprise) with feature comparison"

### modify\_frontend

Surgical redesign of existing components with absolute precision.

**Use when:** An existing element needs visual redesign (not logic changes).

**Input:** The specific code to modify, the modification you want, file path.

**Output:** Find/replace instructions with the redesigned code.

Example prompt

"Make this card look more premium with glassmorphism and subtle shadows"

### snippet\_frontend

Generate standalone UI components to inject into existing files.

**Use when:** You need to add a new UI element to an existing page.

**Input:** What to create, where it goes, your tech stack, design context.

**Output:** Ready-to-insert JSX/HTML snippet matching your design system.

Example prompt

"Add a search dropdown with results in the header"

### Context Isolation

Zero risk of breaking backend logic while styling.

Gemini only receives the relevant frontend context needed for the design task. Your backend logic, API keys, database schemas, and sensitive code are never sent.

**How it works:** Your agent analyzes the request and extracts only the styling context (CSS variables, component structure, design tokens) before sending to Gemini.

**Benefit:** Style freely without worrying about breaking functionality or exposing sensitive code.

### Responsive First

Everything generated is mobile-optimized by default.

Every component Gemini generates includes smart breakpoints for mobile, tablet, and desktop. No additional prompting needed.

**Built-in breakpoints:** Tailwind's responsive prefixes (sm, md, lg, xl) are applied intelligently based on the component type.

**Benefit:** Ship responsive UIs without manually adding media queries or testing each breakpoint.

### Direct File Write

Zero lag filesystem access for instant code delivery.

Generated code is written directly to your project files. No copy-paste, no context switching, no manual file creation.

**How it works:** The MCP server has filesystem access to your workspace. When Gemini generates code, it's saved to the exact path specified.

**Benefit:** See changes instantly in your editor. Hot reload picks up the new files automatically.

1

#### You ask your agent

Write in natural language what you want. No special syntax needed.

"Create a dashboard with user stats and a chart"

2

#### Agent analyzes the request

Your agent (Claude, Cursor, etc.) understands you need frontend work and decides to use Gemini.

Agent thinks: this is UI work → use Gemini Design MCP

3

#### Gemini generates the design

Gemini creates production-ready React/Tailwind code that matches your project's style.

Generates responsive, accessible, polished UI

4

#### Code is written to your project

The generated code is automatically saved to your files. No copy-paste needed.

File saved: app/dashboard/page.tsx

Key point

You never interact with Gemini directly. You just talk to your agent normally, and it uses Gemini when needed for design work.

#### Create from scratch

*   "Create a pricing page with 3 tiers"
*   "Build me a dashboard with charts and stats"
*   "Make a landing page for my SaaS"
*   "Create a settings page with tabs"
*   "Build a login page with social auth buttons"

#### Redesign existing

*   "Make this header look more modern"
*   "Redesign this card to be more premium"
*   "This table looks ugly, fix it"
*   "Make the sidebar look like Stripe's"
*   "This form looks dated, refresh it"

#### Add components

*   "Add a search bar to the header"
*   "Add a notification dropdown"
*   "Add a dark mode toggle"
*   "Add a user avatar menu"
*   "Add a stats section above the table"

#### Style & polish

*   "Make everything more compact"
*   "Use a darker color scheme"
*   "Add more spacing between sections"
*   "Make buttons more rounded"
*   "Add subtle animations"

#### Be specific about what you want

Avoid

"Make a card"

Better

"Make a pricing card with 3 tiers, dark theme, highlighted Pro option"

#### Mention existing styles to match

Avoid

"Add a sidebar"

Better

"Add a sidebar that matches the header style"

#### Iterate in small steps

Avoid

"Create a full dashboard with everything"

Better

"Create the stats section first, then we'll add charts"

#### Reference real products for style

Avoid

"Make it look good"

Better

"Make it look like Stripe's dashboard"

#### Do I need to learn any new syntax?

No. You just talk to your agent normally. Say 'create a login page' or 'make this header look better' - your agent handles the rest.

#### What if I don't like the result?

Just ask for changes! Say 'make it more compact', 'use darker colors', or 'add more spacing'. Iterate until you're happy.

#### Does it work with my existing code?

Yes. Gemini analyzes your existing styles and generates code that matches. It won't break your design system.

#### What tech stack does it support?

Primarily React + Tailwind CSS. It can also work with Vue, vanilla HTML/CSS, and other frameworks.

#### Is my code sent to external servers?

Only the relevant context needed for the design request is sent to Gemini. Your full codebase stays local.

#### What's the free tier limit?

10K tokens per month. That's roughly 6-10 component generations. Paid plans offer more.

### Ready to start?

Get your API key and start building beautiful UIs.

[Get API Key](https://gemini-design-mcp.com/dashboard/api-keys)

---