# Visily MCP

Visily is an AI design canvas that turns text prompts, screenshots, URLs & more into UI
designs that are as easy to edit as a Google Slide. The Visily MCP server brings those
designs into your AI coding agent: point it at a Visily board or screen and your agent can
find it, turn it into application code, or pull its theme tokens.

> [!NOTE]
> **Access requirement.** The Visily MCP works only on workspaces on a **Pro or Business**
> plan where you are the workspace creator or have an **editor** license. Free workspaces and
> viewer/guest roles are not supported. This is enforced on every request.

## What you can do

- **Turn a Visily design into code.** Generate production-ready code from a Visily screen or
  board — whether the UI was AI-generated in Visily or hand-authored. The agent rebuilds
  semantic, responsive components (default stack: React + TypeScript + Tailwind v4 +
  shadcn/ui) instead of pasting a static export.
- **Find a board or screen and get its link.** Ask for a design by description
  (*"the board I was working on for the 4.6 release"*) and the agent returns a link to open
  it — without leaving your editor.
- **Apply a board's theme.** Pull a board's design system as shadcn/Tailwind v4 tokens and
  apply it to another app's styling.

## Install & connect

Authentication is **OAuth** — your client prompts you to sign in to Visily on first use.
There are no API keys to manage.

The current Visily MCP server URL is:

```
https://app.visily.ai/api/mcp
```

Each platform's drop-in files live under [`plugins/<platform>/`](plugins/).

### Claude Code

```bash
claude plugin marketplace add visily-app/mcp-plugins
claude plugin install visily@visily
```

Then reload Claude Code and run `/mcp` → select `visily` → complete the OAuth sign-in. Full
walkthrough: [`installation-guides/claude.md`](installation-guides/claude.md).

### Cursor

Cursor 2.5+ packaged plugin — install from a local clone in the agent chat:

```
/add-plugin ./plugins/cursor
```

Reload Cursor; the MCP server appears under **Settings → MCP** (OAuth on first use) and the
Visily skill loads automatically. Details: [`plugins/cursor/README.md`](plugins/cursor/README.md).

### Cline

Cline can connect directly to the hosted Visily MCP server with Streamable HTTP:

```json
{
  "mcpServers": {
    "visily": {
      "type": "streamableHttp",
      "url": "https://app.visily.ai/api/mcp"
    }
  }
}
```

Full agent-readable install guidance: [`llms-install.md`](llms-install.md).

### Codex

```bash
codex plugin marketplace add visily-app/mcp-plugins
codex plugin add visily@visily
```

Authorize via OAuth on first use. Full walkthrough:
[`installation-guides/codex.md`](installation-guides/codex.md).

### ChatGPT

ChatGPT connects to remote MCP servers via **Developer Mode** custom connectors (Plus, Pro,
Business, or Enterprise). Enable **Settings → Connectors → Advanced → Developer mode**, add a
custom connector pointing at the server URL above, and complete OAuth. Then paste
[`plugins/chatgpt/AGENTS.md`](plugins/chatgpt/AGENTS.md) into a Project/GPT's instructions.
Steps: [`plugins/chatgpt/SETUP.md`](plugins/chatgpt/SETUP.md).

### Antigravity

Copy [`plugins/antigravity/.agents/`](plugins/antigravity) into your project root and merge
[`plugins/antigravity/mcp_config.json`](plugins/antigravity/mcp_config.json) into your global
MCP config. Details: [`installation-guides/antigravity.md`](installation-guides/antigravity.md).

### Kiro

Copy [`plugins/kiro/`](plugins/kiro) into your Kiro powers directory (it contains `POWER.md`,
per-intent `steering/` workflows, and `mcp.json`). Merge `mcp.json` into your Kiro MCP config
and authorize via OAuth. The Power activates on Visily URLs and find/build/theme intents.

### Replit Agent

Install the hosted Visily MCP server with a one-click Replit install link:
[`installation-guides/replit.md`](installation-guides/replit.md).

### Lovable

Commit [`plugins/lovable/AGENTS.md`](plugins/lovable/AGENTS.md) to your repo root and add the
Visily MCP connector in the Lovable UI. Details:
[`plugins/lovable/SETUP.md`](plugins/lovable/SETUP.md).

### v0 (Vercel)

[v0](https://v0.app) supports custom MCP servers natively. Add the server URL above via
**Settings → MCP Connections** (or **Add MCP** in the prompt form) and authorize via OAuth,
then commit [`plugins/v0/AGENTS.md`](plugins/v0/AGENTS.md) to your repo root. Details:
[`plugins/v0/SETUP.md`](plugins/v0/SETUP.md).

### Other editors (Streamable HTTP)

Any client that supports Streamable-HTTP MCP can connect with this config:

```json
{
  "mcpServers": {
    "visily": {
      "url": "https://app.visily.ai/api/mcp"
    }
  }
}
```

This covers VS Code (Copilot), Windsurf, Cline, Gemini CLI, and similar tools. Check your
client's docs for where MCP server config lives; OAuth runs on first use.

> [!NOTE]
> **Google AI Studio** does not natively support MCP connectors yet (it only works through
> third-party browser bridges, which we don't recommend). For a Google-native option, use
> **Firebase Studio**, which supports MCP servers via `.idx/mcp.json` — drop the same `url`
> config there. We'll add a first-class recipe when AI Studio ships native MCP support.

## Prompting your agent

Give the agent a Visily link and a clear intent. The agent extracts the IDs from the URL —
it doesn't open the page.

**Examples**

- "Find the Visily board I was working on for the 4.6 release and give me the link."
- "Build this Visily screen as React + Tailwind: `https://app.visily.ai/projects/abc/boards/456/elements/789`"
- "Implement this board in Next.js, reusing my `src/components/ui` components."
- "Apply my Visily board theme to this app's `globals.css`."

A Visily URL looks like:

```
https://app.visily.ai/projects/{projectId}/boards/{boardId}/elements/{elementId}
```

## Structure your Visily file for better code

The more intent your design carries, the better the generated code:

- **Name your screens and key groups semantically** in Visily — names flow into the export
  and into the link-matching for "find my board."
- **Lean on Visily's theme / design system** so the agent can apply real tokens instead of
  guessing colors and radii.
- **Ask for one screen at a time** for large boards — smaller selections produce more
  reliable results.

## Tools

| Tool | Use |
|---|---|
| `get_design_context` | **Primary.** Returns `designData` + theme + screenshot metadata for one element. |
| `get_screenshot` | Fetch a screenshot for visual verification. |
| `get_board_theme` | Board design system as shadcn tokens (`JSON` / `CSS` / `Tailwind`). |
| `list_workspaces`, `list_projects`, `list_boards`, `list_elements` | Discovery / find-a-board. |
| `get_workspace`, `get_project`, `get_board`, `get_element`, `get_element_export` | Advanced — metadata and raw exports rarely needed for the three use cases; prefer the tools above. |

The server also ships **prompts** (e.g. `find_visily_board`, `generate_code_from_element`,
`apply_board_theme`) and **resources** (`visily://docs/...`) that your agent reads on demand.

## Custom rules (optional)

Set project-level guidance so output stays consistent — like onboarding notes for a new
teammate.

**Cursor** (`.cursor/rules/visily-quality.mdc`):

```yaml
---
description: Visily code-generation rules
alwaysApply: false
---
- Treat Visily `designData` as a reference, not final code — rebuild semantically.
- Apply the Visily `theme` tokens; never hardcode hex, radii, or spacing.
- Reuse existing components in `src/components/ui` instead of duplicating.
- Verify against `get_screenshot` for 1:1 layout before finishing.
```

**Claude Code** (`CLAUDE.md`):

```markdown
## Visily MCP rules
- Treat Visily `designData` as a reference, not final code — rebuild semantically.
- Apply the Visily `theme` tokens; never hardcode hex, radii, or spacing.
- Reuse existing components instead of duplicating; verify with `get_screenshot`.
```

## How this repo is built

`plugins/` is generated from a single shared source (`shared/`) by `scripts/build.mjs`. To
change the integration, edit `shared/` and run `npm run build` — never edit `plugins/` by
hand. See [`CONTRIBUTING.md`](CONTRIBUTING.md).