# Framer MCP Server

An MCP server that connects Claude Code, Cursor, or any MCP client to your Framer project. Read your site, edit CMS content, design pages with a canvas DSL, manage code components, and preview changes locally -- all from your editor.

## Setup

### 1. Get your Framer API key

1. Open your project in Framer
2. Go to **Site Settings > General**
3. Scroll to **API** and create a new key
4. Copy the project URL from your browser (e.g. `https://framer.com/projects/MyProject--abc123`)

### 2. Configure MCP

Add to your `.mcp.json` (Claude Code) or MCP settings (Cursor):

```json
{
  "mcpServers": {
    "framer": {
      "command": "npx",
      "args": ["-y", "framer-mcp-server"],
      "env": {
        "FRAMER_PROJECT_URL": "https://framer.com/projects/YourProject--abc123",
        "FRAMER_API_KEY": "fr_your_api_key_here"
      }
    }
  }
}
```

Or install globally:

```bash
npm install -g framer-mcp-server
```

## Tools

### Project

| Tool | Description |
|------|-------------|
| `framer_mcp_get_project_info` | Returns project name, URLs, and connection status |

### CMS

| Tool | Description |
|------|-------------|
| `framer_mcp_list_collections` | Lists all CMS collections with item/field counts |
| `framer_mcp_get_collection_fields` | Returns field names, types, and IDs for a collection |
| `framer_mcp_get_collection_items` | Lists items in a collection (title, slug, draft status) |
| `framer_mcp_get_collection_item` | Returns full field data for a single item |
| `framer_mcp_add_collection_items` | Adds or updates items (upsert). Returns previous state for undo |
| `framer_mcp_remove_collection_items` | Deletes items by ID. Returns previous state for undo |

### Design

| Tool | Description |
|------|-------------|
| `framer_mcp_get_page_context` | Returns DSL command docs + project fonts, components, tokens |
| `framer_mcp_read_page` | Queries page structure (site-map, node-by-id, components) |
| `framer_mcp_apply_changes` | Pushes visual changes to the Framer canvas via DSL commands |
| `framer_mcp_get_code_files` | Lists code component files in the project |
| `framer_mcp_set_code_file` | Creates or updates a code component file |

### Preview & Publish

| Tool | Description |
|------|-------------|
| `framer_mcp_preview` | Generates a local HTML preview and opens it in the browser |
| `framer_mcp_publish` | Creates a deployment and returns the preview URL |

## Usage Examples

### Browse your site

```
"What pages does my site have?"
→ Uses framer_mcp_read_page with site-map query

"Show me the homepage structure"
→ Uses framer_mcp_get_page_context + framer_mcp_read_page with node-by-id
```

### Edit CMS content

```
"Update the title of my AI project to 'AI Sommelier v2'"
→ Uses framer_mcp_get_collection_items to find the item
→ Uses framer_mcp_add_collection_items to update it
```

### Design changes

```
"Make the hero section full-screen with centered text"
→ Uses framer_mcp_get_page_context for DSL docs
→ Uses framer_mcp_read_page to get current hero node
→ Uses framer_mcp_apply_changes with DSL commands
→ Uses framer_mcp_preview to generate local preview
```

### Preview before pushing

```
"Preview the homepage"
→ Uses framer_mcp_preview to generate HTML and open in browser

"Publish to staging"
→ Uses framer_mcp_publish to deploy and return the preview URL
```

## How It Works

The server connects to your Framer project via the [Framer Server API](https://www.framer.com/developers/server-api) using a WebSocket connection. It translates MCP tool calls into Framer API operations:

- **CMS tools** use collection/item CRUD methods
- **Design tools** use the Framer agent DSL (`applyAgentChanges`, `readProjectForAgent`) for canvas manipulation
- **Preview** reads the full page node tree and converts it to styled HTML
- **Code tools** use `createCodeFile` / `setFileContent` for React components

All write operations (CMS add/remove, design changes) include undo support by snapshotting previous state.

## Development

```bash
git clone https://github.com/ericpjtsai/framer-mcp-server.git
cd framer-mcp-server
npm install
cp .env.example .env  # Add your credentials
npm run dev
```

## License

MIT