|
| 1 | +--- |
| 2 | +description: Get started with the CMS developer MCP. |
| 3 | +--- |
| 4 | + |
| 5 | +# Developer Model Context Protocol (MCP) server |
| 6 | + |
| 7 | +The Developer [MCP Server](./concepts/model-context-protocol.md#mcp-servers) makes it straightforward for developers to connect AI tools with Umbraco. It allows you to harness large language models (LLMs) to perform almost any task that can be achieved within the Umbraco backoffice. This includes generating and editing content, managing media, automating workflows, and assisting with complex development tasks. |
| 8 | + |
| 9 | +This MCP Server acts as a secure gateway between your Umbraco installation and MCP-compatible AI environments. These include Claude (Desktop or Code), Cursor, or GitHub Copilot and many more. |
| 10 | + |
| 11 | +Through this bridge, your AI assistant can interact directly with Umbraco's Management API. This enables a more natural, conversational way to develop and maintain your sites. |
| 12 | + |
| 13 | +{% hint style="info" %} |
| 14 | +Think of it as giving your AI tools a secure, structured way to “speak to Umbraco.” |
| 15 | +{% endhint %} |
| 16 | + |
| 17 | +## How does it work |
| 18 | + |
| 19 | +Unlike most Umbraco integrations, the Developer CMS MCP Server is not a plugin that you install into your Umbraco site. |
| 20 | +Instead, it runs as a standalone Node.js application that acts as an MCP server. |
| 21 | + |
| 22 | +[MCP clients](./concepts/model-context-protocol.md#mcp-clients) are implemented inside compatible [host applications](./concepts/model-context-protocol.md#host-applications) such as Claude Desktop, Cursor, or Windsurf. These clients connect to this server. When you interact with your chat-based development environment, the client communicates with the MCP Server using the Model Context Protocol (MCP). |
| 23 | + |
| 24 | +Learn more about [Model Context Protocol (MCP)](./concepts/model-context-protocol.md) |
| 25 | + |
| 26 | +The MCP Server, in turn, talks directly to Umbraco through the Management API. This is the same API layer that powers the Umbraco backoffice and allows the server to directly read from and modify the CMS. |
| 27 | + |
| 28 | +By exposing these endpoints as MCP tools, the Developer MCP Server enables you to perform almost any backoffice action. You can do this through natural language interaction with your LLM-powered chat environment. |
| 29 | + |
| 30 | +{% hint style="info" %} |
| 31 | +The MCP Server acts as the bridge between your Umbraco instance and your AI assistant. It translates and adapts your tasks into Management API calls. |
| 32 | +{% endhint %} |
| 33 | + |
| 34 | +## Who is this for? |
| 35 | + |
| 36 | +**The Developer MCP Server is designed specifically to be used by Umbraco developers.** |
| 37 | + |
| 38 | +While the Model Context Protocol (MCP) can be used for many types of solution, automation, and workflow integrations. This particular MCP Server focuses on developer-oriented tasks and productivity enhancements within Umbraco projects. |
| 39 | + |
| 40 | +Example use cases: |
| 41 | + |
| 42 | +- **Automation of content, media and schema** |
| 43 | +Automate repetitive actions through conversational commands. This includes creating or updating content or media, generating content models, or performing large-scale operations. |
| 44 | + |
| 45 | +- **Developer quality-of-life improvements** |
| 46 | +Speed up tasks that would otherwise take time or require numerous clicks in the backoffice UI. Examples include batch-moving Document Types or Data Types, cleaning up unused entities, or synchronising content structures. |
| 47 | + |
| 48 | +- **Integration into modern development workflows** |
| 49 | +Use the Developer MCP Server alongside other MCP servers such as Playwright MCP, Figma MCP, or GitHub MCP. This streamlines your end-to-end site development process. |
| 50 | + |
| 51 | +- **Leveraging LLM reasoning** |
| 52 | +Use your LLM to understand, debug, or make better decisions. For example, ask it to interpret entries from Umbraco Logs, suggest schema changes, or explain configuration errors. |
| 53 | + |
| 54 | +- [**Plus many, many more**](./scenarios.md) |
| 55 | + |
| 56 | +**Not recommended for non-developers** |
| 57 | + |
| 58 | +While it’s technically feasible for non-developers to connect to Umbraco using this MCP server, we do not recommend it for the following reasons: |
| 59 | + |
| 60 | +- **Complex setup requirements** |
| 61 | +This MCP server must be run locally, and it requires a configured Umbraco user account with appropriate permissions. |
| 62 | + |
| 63 | +- **Powerful tool access** |
| 64 | +Even for users with limited permissions, the MCP Server exposes many management-level tools. Incorrect commands could unintentionally alter or damage your Umbraco instance. |
| 65 | + |
| 66 | +{% hint style="warning" %} |
| 67 | +Do not connect the Developer MCP Server to a production Umbraco environment. |
| 68 | +Always use a local or isolated development instance. |
| 69 | +{% endhint %} |
| 70 | + |
| 71 | +We are actively working on additional MCP servers tailored to other roles such as editors and content managers. These will provide safer, simplified toolsets and workflows. |
| 72 | + |
| 73 | +## Getting started |
| 74 | + |
| 75 | +### Umbraco Setup |
| 76 | + |
| 77 | +Before connecting the MCP Server, you need to create an [API User](../../fundamentals/data/users/api-users.md) in Umbraco. This user allows the MCP Server to communicate securely with the Management API. |
| 78 | + |
| 79 | +The level of access you assign to this API user determines what actions your AI agent can perform. |
| 80 | +For example: |
| 81 | + |
| 82 | +- A user with Editor permissions can manage and update content but cannot modify Document Types or perform administrative tasks. |
| 83 | +- A user with Administrator permissions grants full access to all capabilities. This includes the ability to create, edit, or delete document types, data types, and more within Umbraco. |
| 84 | + |
| 85 | +{% hint style="warning" %} |
| 86 | +Only use a dedicated API user for MCP connections. |
| 87 | +Do not share or reuse credentials from an existing backoffice user. |
| 88 | +{% endhint %} |
| 89 | + |
| 90 | +### Host Setup |
| 91 | + |
| 92 | +Each MCP-compatible host application has its own setup process. For this reason, we provide dedicated setup guides for the main developer environments we see most often: |
| 93 | + |
| 94 | +[Claude Desktop](./host-setup/claude-desktop.md) |
| 95 | +[Claude Code](./host-setup/claude-code.md) |
| 96 | +[GitHub Copilot](./host-setup/github-copilot.md) |
| 97 | +[Cursor](./host-setup/cursor.md) |
| 98 | + |
| 99 | +Although the details vary slightly, the general pattern is the same across all hosts: |
| 100 | + |
| 101 | +``` json |
| 102 | +{ |
| 103 | + "umbraco-mcp": { |
| 104 | + "command": "npx", |
| 105 | + "args": ["@umbraco-cms/mcp-dev@beta"], |
| 106 | + "env": { |
| 107 | + "NODE_TLS_REJECT_UNAUTHORIZED": "0", |
| 108 | + "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp", |
| 109 | + "UMBRACO_CLIENT_SECRET": "1234567890", |
| 110 | + "UMBRACO_BASE_URL": "https://localhost:12345", |
| 111 | + "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type" |
| 112 | + } |
| 113 | + } |
| 114 | +} |
| 115 | + |
| 116 | +``` |
| 117 | + |
| 118 | +Add your Umbraco MCP configuration values (Client ID, Client Secret, URL of Umbraco) in the appropriate section of your host setup. Then restart the MCP Server or, in some cases, restart the host application itself. |
| 119 | + |
| 120 | +Once restarted, you’ll have access to the full suite of tools available through the Umbraco CMS Developer MCP Server. |
| 121 | + |
| 122 | +{% hint style="info" %} |
| 123 | +This Developer MCP Server requires Node.js version 22 or higher to be installed. |
| 124 | +You can check your current Node.js version by running node -v in your terminal. |
| 125 | +{% endhint %} |
| 126 | + |
| 127 | +#### Never Use Against Production Environments |
| 128 | + |
| 129 | +{% hint style="danger" %} |
| 130 | +**Critical: Do not connect the Developer MCP Server to a production Umbraco environment.** |
| 131 | + |
| 132 | +The Developer MCP Server provides powerful, direct access to your Umbraco Management API. While this makes it a good tool for development and testing, mistakes can have serious consequences. Misconfigurations or misunderstood commands can cause immediate and potentially destructive damage. |
| 133 | + |
| 134 | +**Always use the Developer MCP Server with:** |
| 135 | +- Local development instances only |
| 136 | +- Isolated staging or test environments |
| 137 | +- Environments where data loss or corruption would not impact live users or business operations |
| 138 | + |
| 139 | +**Never connect to:** |
| 140 | +- Production websites |
| 141 | +- Live client sites |
| 142 | +- Any environment where content, media, or configuration changes could affect real users |
| 143 | + |
| 144 | +Even with limited user permissions, the scope and power of LLM-driven actions make this tool unsuitable for production use. |
| 145 | +{% endhint %} |
| 146 | + |
| 147 | +### Choosing Your Tools |
| 148 | + |
| 149 | +Your first step after setup should be deciding which tools you want to enable. |
| 150 | +All tools are grouped into collections for easier management and isolation. |
| 151 | + |
| 152 | +[Learn more about Tool Collections](./available-tools.md) |
| 153 | + |
| 154 | +Choosing the right tools improves how efficiently the AI communicates with Umbraco, making each conversation faster and more context-aware. |
| 155 | + |
| 156 | +[Learn more about Context Engineering](./concepts/context-enginerring.md) |
| 157 | + |
| 158 | +### Why Use npx? |
| 159 | + |
| 160 | +We recommend launching the Developer MCP Server using npx. |
| 161 | +This allows you to run the Node.js application without needing to install anything globally. |
| 162 | +npx will temporarily download the package, execute it, and clean up automatically — ensuring you’re always using the latest version. |
| 163 | + |
| 164 | +If you prefer, you can also install it globally with: |
| 165 | + |
| 166 | +``` bash |
| 167 | + |
| 168 | +npm install -g @umbraco/mcp-server |
| 169 | + |
| 170 | +``` |
| 171 | + |
| 172 | +For advanced configuration options and environment variable settings, see the [Configuration guide](./configuration.md). |
| 173 | + |
| 174 | +## Working with the MCP Server |
| 175 | + |
| 176 | +Once your MCP server is configured and connected, explore these guides to get the most out of your setup: |
| 177 | + |
| 178 | +- [Creating Media](./creating-media.md) - Learn how to upload and manage media items programmatically |
| 179 | +- [Available Tools](./available-tools.md) - Complete reference of all available tools and collections |
| 180 | +- [Scenarios](./scenarios.md) - Real-world examples and use cases |
| 181 | +- [Best Practices](./best-practice/README.md) - Tips for effective MCP usage |
| 182 | + |
| 183 | +## Version Compatibility |
| 184 | + |
| 185 | +The Umbraco MCP Server is designed to work with specific major versions of Umbraco CMS: |
| 186 | + |
| 187 | +| MCP Server Version | Compatible Umbraco Version | NPM Package Name | |
| 188 | +|--------------------|----------------------------|--------------------------------------| |
| 189 | +| 15.x.x | alpha | @umbraco-mcp/umbraco-mcp-cms@alpha | |
| 190 | +| 16.x.x | all betas, 16.x | @umbraco-cms/mcp-dev@beta | |
| 191 | + |
| 192 | +### Version Checking |
| 193 | + |
| 194 | +The MCP server automatically checks version compatibility on startup: |
| 195 | + |
| 196 | +- **✅ Version Match**: No message displayed, server functions normally |
| 197 | +- **⚠️ Version Mismatch**: The first tool request will fail with an error message asking you to retry if you want to proceed. After you retry, the warning displays once more. It is then never shown again for that session. |
| 198 | +- **⚠️ API Error**: If the version check API call fails, a warning is displayed once but does not block tool execution. |
| 199 | + |
| 200 | +The version check uses the Umbraco Management API endpoint `/umbraco/management/api/v1/server/information` to detect the connected Umbraco version and compares the major version number. |
| 201 | + |
0 commit comments