Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

MCP troubleshooting

Solutions for the most common issues when connecting the Framer MCP plugin to AI assistants.

Windows: URL with & breaks the command

Symptom: On Windows, the & in the MCP URL is interpreted as a command separator. You see errors like 'secret' is not recognized as an internal or external command.
Fix: Wrap the entire URL in double quotes in your configuration:
{
    "mcpServers": {
        "framer": {
            "url": "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
        }
    }
}
If you are using the mcp-remote bridge, wrap the URL in quotes in the args array:
{
    "mcpServers": {
        "framer": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
            ]
        }
    }
}

OAuth 404 / SSE 405 errors

Symptom: Claude Desktop shows OAuth discovery on mcp.unframer.co returns HTTP 404 or SSE fallback returns HTTP 405.
Fix: These errors typically mean Claude Desktop is trying an older MCP transport that is not supported. Solutions:
  1. Use mcp-remote as a bridge. This handles the transport negotiation for you:
    {
    "mcpServers": {
        "framer": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.unframer.co/mcp?id=YOUR_ID&secret=YOUR_SECRET"
            ]
        }
    }
}
  2. Update Claude Desktop to the latest version. Newer versions support StreamableHTTP transport natively.
  3. If you have a Claude Max subscription, use the Connectors feature instead (Settings → Connectors → paste the MCP URL directly).

WebSocket disconnects on write commands (error 1006/1001)

Symptom: Read operations (getProjectXml, getNodeXml) work fine, but write operations (updateXmlForNode) immediately disconnect with WebSocket error code 1006 or 1001.
Fix: This is usually a network stability issue. The write operations take longer and are more sensitive to connection drops.
  1. Close other browser extensions that might interfere with WebSocket connections (ad blockers, privacy extensions, VPNs)
  2. Try a different network. If you are on corporate WiFi, try a phone hotspot
  3. Restart the Framer desktop app (not just the browser tab)
  4. Reconnect the MCP in your AI tool settings after restarting
  5. If the issue persists, try using Server API mode via the unframer CLI instead
Some corporate firewalls and proxy servers interfere with WebSocket connections. If you're on a managed network, ask your IT team about WebSocket policies.

Multi-account MCP conflicts

Symptom: You have two Framer accounts connected via MCP, but only the first one works. The second account shows as connected (green dot) but the AI says "Framer MCP plugin isn't currently connected."
Fix: The MCP identity is per session. Only one account can be active at a time.
  1. Disconnect the first account from your AI tool entirely (remove the MCP server config)
  2. Close the MCP plugin in the first account's Framer project
  3. Open the MCP plugin in the second account's project
  4. Re-add the MCP server in your AI tool with the second account's URL
You cannot use two Framer accounts simultaneously through MCP.

Secret rotation / exposed URL

Symptom: Your MCP URL was accidentally shared (posted on GitHub, shared in a screenshot) and you want to revoke it.
Fix: Contact [email protected] with your MCP URL or Framer email. The session will be revoked within minutes.
After revocation:
  1. Open the Framer MCP plugin
  2. Log out and log back in
  3. Copy the new MCP URL
  4. Update your AI tool configuration with the new URL
The MCP URL contains a session secret that grants access to your Framer project. Treat it like a password. Never commit it to public repositories.

Connection timeouts

Symptom: The AI tool shows a timeout after 30-60 seconds when trying to connect.
Fix checklist:
  1. Is the Framer MCP plugin open? The plugin must be open and showing a green status indicator
  2. Did you open the plugin BEFORE configuring the AI tool? Some tools cache the connection state. Open the plugin first, then configure
  3. Are you using React Export? Publishing is only needed for React Export or tools that read the published website URL. Canvas and CMS operations work without publishing
  4. Restart the MCP plugin. Close it (click the X in Framer) and reopen it. This resets the WebSocket connection
  5. Restart your AI tool. Cursor, Claude Desktop, etc. may need a restart to pick up config changes

Cursor doesn't show Framer tools

Symptom: Cursor is configured but doesn't list Framer MCP in available tools.
Fix:
  1. Make sure you have a Cursor Pro subscription (Agent mode requires Pro)
  2. Enable Agent mode in Cursor settings
  3. Check that the config file is in the right location: .cursor/mcp.json in your project root, or ~/.cursor/mcp.json globally
  4. Restart Cursor after saving the config
  5. Open the Agent panel and ask "What tools do you have available?"

Quick diagnostic

If something isn't working, ask your AI assistant:
Do you have access to the Framer MCP tool?
Then try a small read operation:
Get the project structure
If reads work but writes fail, it is likely a network or timeout issue. If nothing works, the plugin is not connected or the URL is wrong.
Powered byHolocron