Docs
01 / Setup

Getting Started

Get Gemini Design working with your AI agent in under 2 minutes.

1

Get your API Key

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

Go to Dashboard
2

Configure your tool

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

Run in terminal
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

2. Existing project: ALWAYS pass CSS/theme files in context

3. After response: Gemini returns code → YOU write it to disk

## ❌ FORBIDDEN

  • Writing React components with styling without Gemini
  • Creating pages without Gemini
  • Doing frontend "quickly" yourself

## ✅ EXPECTED

  • Call Gemini BEFORE writing any frontend code
  • Ask user for vibe choice if new project
  • Let Gemini design, you implement

You're ready!

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

02 / Connection

Remote Server Mode

Connect to our hosted MCP server without installing anything locally.

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.

  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.

03 / Tools

Core Tools

Six specialized tools designed for high-precision frontend iteration.

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.

04 / Flow

How It Works

You talk to your agent normally. Gemini works in the background.

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.

05 / Examples

What You Can Ask

Here are examples of things you can ask your agent. Just talk naturally.

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"
06 / Tips

Getting Better Results

A few tips to get the most out of Gemini Design.

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"

07 / FAQ

Common Questions

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