Gravity MCP Server

Model Context Protocol server for the Gravity Design System.

Let AI assistants install and use Gravity components in any project with a single command.

Quick Start

1. Install globally

npm install -g @gravity-ai/mcp-server

2. Add to your AI assistant

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gravity": {
      "command": "gravity-mcp"
    }
  }
}

Then restart Cursor.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gravity": {
      "command": "gravity-mcp"
    }
  }
}

Then restart Claude Desktop.

3. Use it!

In your AI assistant, say:

"Use the Gravity design system to redesign this project's frontend"

or

"Install Gravity and update this button to use the design system"

What It Does

The MCP server provides three types of capabilities:

🔧 Tools (Actions)

| Tool | Description | |------|-------------| | gravity_install | Installs all 50 components, design tokens, and utilities | | gravity_verify | Verifies installation succeeded and reports missing files | | gravity_diagnose | Scans for common issues (CSS conflicts, wrong imports, etc.) | | gravity_list_components | Lists all available components | | gravity_get_component | Gets the full source code for a specific component | | gravity_check_project | Analyzes project structure for optimal installation |

📚 Resources (Documentation)

| Resource | Content | |----------|---------| | gravity://getting-started | READ FIRST — Workflows for new and existing projects | | gravity://components | Complete component catalog with props and examples | | gravity://tokens | All design tokens (colors, spacing, typography, shadows) | | gravity://guidelines | Brand guidelines, patterns, and anti-patterns | | gravity://icons | Approved icon set (61 Lucide icons) |

💬 Prompts (Workflows)

| Prompt | Description | |--------|-------------| | gravity_new_project | Workflow for building a new project from scratch | | gravity_redesign | Step-by-step workflow to migrate an existing frontend |

Example Conversations

Install Gravity in a new project

You: "Set up this new Next.js project with the Gravity design system"

AI: Uses gravity_check_project to detect structure, then gravity_install to add all components

Redesign existing frontend

You: "Use MCP to redesign the frontend to use Gravity design system"

AI: Uses gravity_redesign prompt which guides through:

1. Installing components
2. Discovering existing UI
3. Mapping components
4. Migrating files in batches

Get a specific component

You: "Show me how to use the StatCard component from Gravity"

AI: Uses gravity_get_component to fetch source, then gravity://components resource for documentation

Manual Installation

If you prefer not to use the global install:

# Clone the repo
git clone https://github.com/Try-Gravity/design-system3.git
cd design-system3/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Configure your AI assistant to use the local path

Then in your MCP config:

{
  "mcpServers": {
    "gravity": {
      "command": "node",
      "args": ["/absolute/path/to/design-system3/packages/mcp-server/dist/index.js"]
    }
  }
}

What Gets Installed

When you run gravity_install, the tool:

1. Copies 50 UI components to src/components/ui/ (or detected location)
   • Button, Card, Input, Badge, Dialog, Table, Toast, and 40+ more
2. Adds the cn() utility to src/lib/utils.ts
   • Merges Tailwind classes intelligently
3. Merges design tokens into your global CSS
   • Colors, spacing, typography, shadows, motion
   • Full dark mode support
4. Updates package.json with required dependencies
   • Radix UI primitives
   • CVA, clsx, tailwind-merge
   • Lucide icons
5. Optionally copies logo assets to public/logos/

Requirements

• Node.js 18+
• A React project (Next.js, Vite, CRA, etc.)
• Tailwind CSS configured

Troubleshooting

"gravity-mcp not found"

Make sure the global npm bin is in your PATH:

npm config get prefix
# Add {prefix}/bin to your PATH

MCP server not connecting

1. Check your config file syntax (JSON)
2. Restart your AI assistant
3. Look for errors in the assistant's console/logs

Components not styling correctly

1. Ensure Tailwind is configured
2. Check that globals.css is imported in your layout
3. Verify content paths in tailwind.config.js include component directory

License

MIT

Gravity Design System — Quiet authority. Calm intelligence. Infrastructure for AI.