Merge pull request #63 from webflow/designer-readmer

victoriaplummer · web-flow · commit 45503cf91261 · 2025-09-16T22:07:26.000-04:00
docs: Add Designer MCP Installation Instructions
diff --git a/README.md b/README.md
@@ -1,23 +1,33 @@
-# Webflow's Official MCP Server
+# Webflow's MCP server
 
 A Node.js server implementing Model Context Protocol (MCP) for Webflow using the [Webflow JavaScript SDK](https://github.com/webflow/js-webflow-api). Enable AI agents to interact with Webflow APIs. Learn more about Webflow's Data API in the [developer documentation](https://developers.webflow.com/data/reference).
 
 [![npm shield](https://img.shields.io/npm/v/webflow-mcp-server)](https://www.npmjs.com/package/webflow-mcp-server)
-[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fwebflow%2Fmcp-server)
+![Webflow](https://img.shields.io/badge/webflow-%23146EF5.svg?style=for-the-badge&logo=webflow&logoColor=white)
 
-## ℹ Prerequisites
+## Prerequisites
 
 - [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
 - [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
 - [A Webflow Account](https://webflow.com/signup)
 
-## ▶️ Quick start (hosted on Cloudflare workers)
+## 🚀 Remote installation
 
-**For Cursor:**
+Get started by installing Webflow's remote MCP server. The remote server uses OAuth to authenticate with your Webflow sites, and a companion app that syncs your live canvas with your AI agent.
 
-1. Go to `Settings` → `Cursor Settings` → `MCP`
-2. Click `+ Add New Global MCP Server`
-3. Paste the following configuration (or add the `webflow` part to your existing configuration)
+### Requirements
+
+- Node.js 22.3.0 or higher
+
+> Note: The MCP server currently supports Node.js 22.3.0 or higher. If you run into version issues, see the [Node.js compatibility guidance.](https://developers.webflow.com/data/v2.0.0/docs/ai-tools#nodejs-compatibility)
+
+### Cursor
+
+#### Add MCP server to Cursor
+
+1. Go to `Settings → Cursor Settings → MCP & Integrations`.
+2. Under MCP Tools, click `+ New MCP Server`.
+3. Paste the following configuration into `.cursor/mcp.json` (or add the `webflow` part to your existing configuration):
 
 ```json
 {
@@ -29,32 +39,47 @@ A Node.js server implementing Model Context Protocol (MCP) for Webflow using the
 }
 ```
 
-4. Save, Cursor will automatically open a new browser window showing an OAuth login page to authorize the Webflow sites you want the MCP server to have access to.
+> Tip: You can create a project-level `mcp.json` to avoid repeated auth prompts across multiple Cursor windows. See Cursor’s docs on [configuration locations.](https://docs.cursor.com/en/context/mcp#configuration-locations)
 
-**For Claude Desktop:**
+4. Save and close the file. Cursor will automatically open an OAuth login page where you can authorize Webflow sites to use with the MCP server.
 
-1. Open `Settings` → `Developer`
-2. Click `Edit Config`
-3. Open `claude_desktop_config.json` in a code editor and paste the following configuration (or add the `webflow` part to your existing configuration)
+#### Open the Webflow Designer
 
-```json
-{
-  "mcpServers": {
-    "webflow": {
-      "command": "npx",
-      "args": ["mcp-remote", "https://mcp.webflow.com/sse"]
-    }
-  }
-}
+- Open your site in the Webflow Designer, or ask your AI agent:
+
+```text
+Give me a link to open <MY_SITE_NAME> in the Webflow Designer
 ```
 
-4. Save the file and restart Claude Desktop (command/ctrl + R). When Claude restarts, it will automatically open a new browser window showing an OAuth login page to authorize the Webflow sites you want the MCP server to have access to.
+#### Open the MCP Webflow App
+
+1. In the Designer, open the Apps panel (press `E`).
+2. Launch your published "Webflow MCP Bridge App".
+3. Wait for the app to connect to the MCP server.
+
+#### Write your first prompt
 
-**For Windsurf:**
+Try these in your AI chat:
 
-1. Navigate to `Windsurf - Settings` → `Advanced Settings`
-2. Scroll down to the `Cascade` section → `Add Server` → `Add custom server +`
-3. Paste the following configuration (or add the `webflow` part to your existing configuration)
+```text
+Analyze my last 5 blog posts and suggest 3 new topic ideas with SEO keywords
+```
+
+```text
+Find older blog posts that mention similar topics and add internal links to my latest post
+```
+
+```text
+Create a hero section card on my home page with a CTA button and responsive design
+```
+
+### Claude desktop
+
+#### Add MCP server to Claude desktop
+
+1. Enable developer mode: `Help → Troubleshooting → Enable Developer Mode`.
+2. Open developer settings: `File → Settings → Developer`.
+3. Click `Get Started` or edit the configuration to open `claude_desktop_config.json` and add:
 
 ```json
 {
@@ -67,88 +92,59 @@ A Node.js server implementing Model Context Protocol (MCP) for Webflow using the
 }
 ```
 
-4. Click `Save`, Windsurf will automatically open a new browser window showing an OAuth login page to authorize the Webflow sites you want the MCP server to have access to.
+4. Save and restart Claude Desktop (`Cmd/Ctrl + R`). An OAuth login page will open to authorize sites.
 
-**For VS Code:**
+#### Open the Webflow Designer
 
-1. Open `settings.json`
-2. Paste the following configuration (or add the `webflow` part to your existing configuration)
+- Open your site in the Webflow Designer, or ask your AI agent:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "webflow": {
-        "command": "npx",
-        "args": ["mcp-remote", "https://mcp.webflow.com/sse"]
-      }
-    }
-  }
-}
+```text
+Give me a link to open <MY_SITE_NAME> in the Webflow Designer
 ```
 
-4. `Save` the file. You should see a `start` button appear over the "webflow" key which you can click to open and run the auth flow. Alternatively, restart VS Code and the auth flow should start automatically.
+#### Open the MCP Webflow App
 
-**Important note**
+1. In the Designer, open the Apps panel (press `E`).
+2. Launch your published "Webflow MCP Bridge App".
+3. Wait for the app to connect to the MCP server.
 
-All these methods rely on the `mcp-remote` [npm package](https://www.npmjs.com/package/mcp-remote) which is still considered experimental as of 04/30/2025.
-If at any point you have issues, and want to reset your OAuth tokens, you can run the following command before restarting your MCP client:
+#### Write your first prompt
 
-```shell
-rm -rf ~/.mcp-auth
+```text
+Analyze my last 5 blog posts and suggest 3 new topic ideas with SEO keywords
 ```
 
-## ▶️ Quick start (local installation)
+```text
+Find older blog posts that mention similar topics and add internal links to my latest post
+```
 
-1. **Get your Webflow API token**
+```text
+Create a hero section card on my home page with a CTA button and responsive design
+```
 
-- Go to [Webflow's API Playground](https://developers.webflow.com/data/reference/token/authorized-by)
-- Log in and generate a token
-- Copy the token from the Request Generator
-  ![Get API Token](https://prod.ferndocs.com/_next/image?url=https%3A%2F%2Ffiles.buildwithfern.com%2Fwebflow-preview-6a549203-c0da-4038-8adf-1dbed286cb83.docs.buildwithfern.com%2F2025-03-28T17%3A56%3A04.435Z%2Fassets%2Fimages%2Fapi-key-playground.png&w=3840&q=75)
+### Reset your OAuth Token
 
-2. **Add to your AI editor**
+To reset your OAuth token, run the following command in your terminal.
 
-```json
-{
-  "mcpServers": {
-    "webflow": {
-      "command": "npx",
-      "args": ["-y", "webflow-mcp-server@0.6.0"],
-      "env": {
-        "WEBFLOW_TOKEN": "<YOUR_WEBFLOW_TOKEN>"
-      }
-    }
-  }
-}
+```bash
+rm -rf ~/.mcp-auth
 ```
 
-**For Cursor:**
+### Node.js compatibility
 
-1. Go to Settings → Cursor Settings → MCP
-2. Click `+ Add New Global MCP Server`
-3. Paste configuration
-4. Replace `YOUR_WEBFLOW_TOKEN` with the token you copied earlier
-5. Save and **restart** Cursor
-
-**For Claude Desktop:**
-
-1. Open Settings → Developer
-2. Click `Edit Config`
-3. Open `claude_desktop_config.json` in a code editor and paste configuration
-4. Replace `YOUR_WEBFLOW_TOKEN` with the token you copied earlier 5. Save and **restart** Claude
+Please see the Node.js [compatibility guidance on Webflow's developer docs.](https://developers.webflow.com/data/v2.0.0/docs/ai-tools#nodejs-compatibility)
 
 ## ❓ Troubleshooting
 
 If you are having issues starting the server in your MCP client e.g. Cursor or Claude Desktop, please try the following.
 
-### Ensure you have a valid Webflow API token
+### Make sure you have a valid Webflow API token
 
 1. Go to [Webflow's API Playground](https://developers.webflow.com/data/reference/token/authorized-by), log in and generate a token, then copy the token from the Request Generator
 2. Replace `YOUR_WEBFLOW_TOKEN` in your MCP client configuration with the token you copied
 3. Save and **restart** your MCP client
 
-### Ensure you have the Node and NPM installed
+### Make sure you have the Node and NPM installed
 
 - [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
 - [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
@@ -176,113 +172,19 @@ Note: if you are making changes to your shell configuration, you may need to res
 
 ## 🛠️ Available tools
 
-### Sites
-
-```
-sites - list; // List all sites
-sites - get; // Get site details
-sites - publish; // Publish site changes
-```
-
-### Pages
-
-```
-pages - list; // List all pages
-pages - get - metadata; // Get page metadata
-pages - update - page - settings; // Update page settings
-pages - get - content; // Get page content
-pages - update - static - content; // Update page content
-```
-
-### Components
-
-```
-components - list // List all components in a site
-components - get - content // Get component content (text, images, nested components)
-components - update - content // Update component content for localization
-components - get - properties // Get component properties (default values)
-components - update - properties // Update component properties for localization
-```
-
-### CMS
-
-```
-collections - list; // List collections
-collections - get; // Get collection details
-collections - create; // Create a collection
-collection - fields - create - static; // Create a static field
-collection - fields - create - option; // Create an option field
-collection - fields - create - reference; // Create a reference field
-collection - fields - update; // Update a custom field
-collections - items - create - item - live; // Create items
-collections - items - update - items - live; // Update items
-collections - items - list - items; // List collection items
-collections - items - create - item; // Create collection items (staged)
-collections - items - update - items; // Update collection items (staged)
-collections - items - publish - items; // Publish collection items
-```
+See the `./tools` directory for a list of available tools
 
-### Custom Code
+# 🗣️ Prompts & resources
 
-```
-custom code - add - inline - site - script // Register an inline script for a site
-custom code - get - registered - site - script - list // List all scripts registered to a site
-custom code - get - applied - site - script - list //Get all scripts applied to a site
-custom code - delete site custom code // Remove scripts from a site
-```
-
-### Components 
-
-```
-components - list; // List all components for a site
-components - content - get; // Get static content from a component definition
-components - content - update; // Update content within a component definition for secondary locales
-components - properties - get; // Get the default property values of a component definition
-components - properties - update; // Update the default property values of a component definition for secondary locales
-```
-
-### Ask Webflow AI 
-
-```
-ask - webflow - ai; // Search Webflow Docs using AI search
-```
-
-# 🗣️ Prompts & Resources
-
-This implementation **does not** include `prompts` or `resources` from the MCP specification. However, this may change in the future when there is broader support across popular MCP clients.
-
-# 🚧 Development mode
-
-If you want to run the server in development mode, you can install dependencies and run the server using the following command:
-
-1. Clone and install:
-
-```shell
-git clone git@github.com:webflow/mcp-server.git
-cd mcp-server
-npm install
-```
-
-2. Add your token to a `.env` file at the root of the project:
-
-```shell
-# .env
-WEBFLOW_TOKEN=<YOUR_WEBFLOW_TOKEN>
-```
-
-3. Start development server:
-
-```shell
-npm start
-```
+This implementation **doesn't** include `prompts` or `resources` from the MCP specification. However, this may change in the future when there is broader support across popular MCP clients.
 
-## 📄 Webflow Developer resources
+## 📄 Webflow developer resources
 
 - [Webflow API Documentation](https://developers.webflow.com/data/reference)
 - [Webflow JavaScript SDK](https://github.com/webflow/js-webflow-api)
 
-## ⚠️ Known Limitations
+## ⚠️ Known limitations
 
-### Static Page Content Updates
+### Static page content updates
 
-The pages_update_static_content endpoint currently only supports updates to localized static pages in secondary locales. Updates to static content in the default locale are not supported and will result in errors.
+The `pages_update_static_content` endpoint currently only supports updates to localized static pages in secondary locales. Updates to static content in the default locale aren't supported and will result in errors.
