Uxmagic MCP Server

A Model Context Protocol (MCP) bridge for UX Magic. It connects your IDE (Cursor, VS Code, Windsurf, Claude, …) to the UX Magic remote MCP server so an AI agent can read, generate and edit your designs.

It is a transparent stdio bridge: it forwards MCP traffic to the UX Magic backend (https://api.uxmagic.ai/api/mcp) over Streamable HTTP using your API key. Because it proxies rather than reimplements, it always exposes the full, current UX Magic toolset — no client update needed when new tools ship.

Features

• Full UX Magic design toolset — projects, frames, themes, documents
• AI design generation (long-running, pollable) and targeted edits
• Resources (uxmagic://…) and guided prompts
• Figma export
• API-key authentication with optional per-key scopes

Tip: modern IDEs can connect to https://api.uxmagic.ai/api/mcp directly (remote MCP over HTTP with an X-API-Key header) and skip this bridge entirely. The bridge exists for clients that only support stdio.

Installation

Running with npx

env UXMAGIC_API_KEY=uxm_YOUR_API_KEY npx -y uxmagic-mcp

Manual Installation

npm install -g uxmagic-mcp

Running on Cursor

Configuring Cursor 🖥️ Note: Requires Cursor version 0.45.6+ For the most up-to-date configuration instructions, please refer to the official Cursor documentation on configuring MCP servers: Cursor MCP Server Configuration Guide

To configure Uxmagic MCP in Cursor v0.48.6

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add new global MCP server"
4. Enter the following code:

   {
     "mcpServers": {
       "uxmagic-mcp": {
         "command": "npx",
         "args": ["-y", "uxmagic-mcp"],
         "env": {
           "UXMAGIC_API_KEY": "YOUR-API-KEY"
         }
       }
     }
   }

To configure Uxmagic MCP in Cursor v0.45.6

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following:
   • Name: "uxmagic-mcp" (or your preferred name)
   • Type: "command"
   • Command: env UXMAGIC_API_KEY=your-api-key npx -y uxmagic-mcp

If you are using Windows and are running into issues, try cmd /c "set UXMAGIC_API_KEY=your-api-key && npx -y uxmagic-mcp"

Replace your-api-key with your Uxmagic API key. Create an API key from your Uxmagic account settings.

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Uxmagic MCP when appropriate, but you can explicitly request it by describing your frame or flow needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "uxmagic-mcp": {
      "command": "npx",
      "args": ["-y", "uxmagic-mcp"],
      "env": {
        "UXMAGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Running on Antigravity

Add this to your MCP config. Config file location:

• macOS/Linux: ~/.gemini/antigravity/mcp_config.json
• Windows: C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

To edit: Open the "..." dropdown in the Agent panel → Manage MCP Servers → View raw config.

{
  "mcpServers": {
    "uxmagic-mcp": {
      "command": "npx",
      "args": ["-y", "uxmagic-mcp"],
      "env": {
        "UXMAGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Antigravity after changing the config.

Connecting directly (no bridge)

If your client supports remote MCP servers, point it straight at the backend and skip this package:

• URL: https://api.uxmagic.ai/api/mcp (transport: Streamable HTTP)
• Header: X-API-Key: uxm_YOUR_API_KEY

Running on VS Code

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Uxmagic API Key",
        "password": true
      }
    ],
    "servers": {
      "uxmagic": {
        "command": "npx",
        "args": ["-y", "uxmagic-mcp"],
        "env": {
          "UXMAGIC_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Uxmagic API Key",
      "password": true
    }
  ],
  "servers": {
    "uxmagic": {
      "command": "npx",
      "args": ["-y", "uxmagic-mcp"],
      "env": {
        "UXMAGIC_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Configuration

Environment Variables

Required for Uxmagic MCP API Authorization

• UXMAGIC_API_KEY: Your Uxmagic API key (required)

Configuration Examples

For cloud API usage:

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "uxmagic-mcp": {
      "command": "npx",
      "args": ["-y", "uxmagic-mcp"],
      "env": {
        "UXMAGIC_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Available capabilities

Tools, resources and prompts are provided by the UX Magic backend and surfaced through this bridge, so the list always reflects the live server. Run tools/list from your client to see the current set. Today it includes:

• Read — list_projects, get_project, list_frames, get_frame, read_screen, read_theme, list_project_documents, read_document
• Write — create_project, create_frame, duplicate_frame, edit_design, update_design, replace_image, export_figma
• AI generation (async) — generate_design → poll generation_status (with cursor) → confirm_generation (human-in-the-loop) / cancel_generation
• Resources — uxmagic://project/{id}, uxmagic://frame/{id}, uxmagic://frame/{id}/version/{versionId}, uxmagic://frame/{id}/theme
• Prompts — design_screen, redesign_screen, build_theme, clone_site, prototype_flow

What a given API key can access depends on its scopes (designs:read, designs:write, agent:run); a key with no scopes has full access.

Logging

The bridge logs to stderr only (stdout is the MCP channel). Example:

[uxmagic-mcp] bridging stdio ⇄ https://api.uxmagic.ai/api/mcp
[uxmagic-mcp] backend transport error: ...

Error Handling

The server provides robust error handling:

• Detailed error messages from Uxmagic API
• API key validation

Example error response:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Uxmagic API error (401): Invalid API key"
    }
  ],
  "isError": true
}

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run
UXMAGIC_API_KEY=uxm_xxx pnpm start

Contributing

1. Fork the repository
2. Create your feature branch
3. Submit a pull request

License

MIT License - see LICENSE file for details