Umbraco-CMS-MCP-Dev — Claude Code MCP server: how to install
An MCP server connecting AI agents directly to the Umbraco Management API. It enables back-office operations on documents and media assets via API user credentials.
claude mcp add --env UMBRACO_CLIENT_ID=<UMBRACO_CLIENT_ID> --env UMBRACO_CLIENT_SECRET=<UMBRACO_CLIENT_SECRET> --env UMBRACO_BASE_URL=<UMBRACO_BASE_URL> --env UMBRACO_INCLUDE_TOOL_COLLECTIONS=<UMBRACO_INCLUDE_TOOL_COLLECTIONS> --env UMBRACO_READONLY=<UMBRACO_READONLY> --transport stdio umbraco-cms-mcp-dev -- npx -y @umbraco-cms/mcp-devWhat Umbraco-CMS-MCP-Dev does
This server connects coding agents to the Umbraco Management API. The assistant can query documents and update media assets without opening the web interface. Access is bound to the Umbraco API user account. Your existing role setup remains in charge.
Running the server locally uses npx. For Umbraco Cloud, the package deploys into a Cloudflare Worker via @umbraco-cms/mcp-hosted. The environment variable UMBRACO_INCLUDE_TOOL_COLLECTIONS filters specific tools. You can also turn on UMBRACO_READONLY for safe inspection.
Pin the package tag to your CMS major version, such as @17 or @18. Tool schemas mirror that specific Management API release. When major versions drift apart, tool calls fail during execution.
What it helps with
- manage Umbraco CMS documents and media without opening the back office
- inspect and modify document types directly from the agent chat
- restrict agent capabilities using the
UMBRACO_READONLYflag - route requests to Umbraco Cloud projects via Cloudflare Workers
Example prompts for the agent
- Inspect all document types configured in the current Umbraco site.
- Create a document using the
blogPosttype under the news section. - Upload the logo asset directly into the media collection.
How to install Umbraco-CMS-MCP-Dev
Platform CLI
claude mcp add --env UMBRACO_CLIENT_ID=<UMBRACO_CLIENT_ID> --env UMBRACO_CLIENT_SECRET=<UMBRACO_CLIENT_SECRET> --env UMBRACO_BASE_URL=<UMBRACO_BASE_URL> --env UMBRACO_INCLUDE_TOOL_COLLECTIONS=<UMBRACO_INCLUDE_TOOL_COLLECTIONS> --env UMBRACO_READONLY=<UMBRACO_READONLY> --transport stdio umbraco-cms-mcp-dev -- npx -y @umbraco-cms/mcp-devReplace <…> with your own values
Platform CLI
codex mcp add umbraco-cms-mcp-dev --env UMBRACO_CLIENT_ID=<UMBRACO_CLIENT_ID> --env UMBRACO_CLIENT_SECRET=<UMBRACO_CLIENT_SECRET> --env UMBRACO_BASE_URL=<UMBRACO_BASE_URL> --env UMBRACO_INCLUDE_TOOL_COLLECTIONS=<UMBRACO_INCLUDE_TOOL_COLLECTIONS> --env UMBRACO_READONLY=<UMBRACO_READONLY> -- npx -y @umbraco-cms/mcp-devReplace <…> with your own values
Config file
{
"mcpServers": {
"umbraco-cms-mcp-dev": {
"command": "npx",
"args": [
"-y",
"@umbraco-cms/mcp-dev"
],
"env": {
"UMBRACO_CLIENT_ID": "<UMBRACO_CLIENT_ID>",
"UMBRACO_CLIENT_SECRET": "<UMBRACO_CLIENT_SECRET>",
"UMBRACO_BASE_URL": "<UMBRACO_BASE_URL>",
"UMBRACO_INCLUDE_TOOL_COLLECTIONS": "<UMBRACO_INCLUDE_TOOL_COLLECTIONS>",
"UMBRACO_READONLY": "<UMBRACO_READONLY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"umbraco-cms-mcp-dev": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@umbraco-cms/mcp-dev"
],
"env": {
"UMBRACO_CLIENT_ID": "<UMBRACO_CLIENT_ID>",
"UMBRACO_CLIENT_SECRET": "<UMBRACO_CLIENT_SECRET>",
"UMBRACO_BASE_URL": "<UMBRACO_BASE_URL>",
"UMBRACO_INCLUDE_TOOL_COLLECTIONS": "<UMBRACO_INCLUDE_TOOL_COLLECTIONS>",
"UMBRACO_READONLY": "<UMBRACO_READONLY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e UMBRACO_CLIENT_ID=<UMBRACO_CLIENT_ID> -e UMBRACO_CLIENT_SECRET=<UMBRACO_CLIENT_SECRET> -e UMBRACO_BASE_URL=<UMBRACO_BASE_URL> -e UMBRACO_INCLUDE_TOOL_COLLECTIONS=<UMBRACO_INCLUDE_TOOL_COLLECTIONS> -e UMBRACO_READONLY=<UMBRACO_READONLY> umbraco-cms-mcp-dev npx -y @umbraco-cms/mcp-devReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Umbraco-CMS-MCP-Dev
How to install Umbraco-CMS-MCP-Dev in Claude Code?
Run this command: `claude mcp add umbraco-cms-mcp-dev -e UMBRACO_CLIENT_ID=<UMBRACO_CLIENT_ID> -e UMBRACO_CLIENT_SECRET=<UMBRACO_CLIENT_SECRET> -e UMBRACO_BASE_URL=<UMBRACO_BASE_URL> -- npx -y @umbraco-cms/mcp-dev`. Replace the placeholders with your Umbraco API user credentials and host URL.
What credentials does Umbraco-CMS-MCP-Dev require?
You must create an Umbraco API user in the back office. The server reads its client ID, client secret, and the base URL of your running CMS instance.
Why should the package version be pinned to the Umbraco major release?
Each package release tracks the Management API schema of a specific Umbraco major version. A version mismatch causes tool schemas to break mid-task.
