umb-cms-mcp-setup

Umbraco MCP Server — Setup Guide

This covers running @umbraco-cms/mcp-dev as a live MCP server connected to an AI client (Claude Desktop, Claude Code, Cursor, VS Code, etc). For debugging the package directly on the command line (--list-tools, --call, --debug-config), see the umb-cms-dev-cli skill instead — the same env vars apply either way.

For install steps, verifying the connection, and troubleshooting, use the official docs rather than this skill — they're the source of truth and won't drift out of sync the way a duplicated copy here would:

Umbraco MCP Documentation

For per-client configuration, go straight to the guide for the client actually in use rather than the general page above:

Prerequisites

An Umbraco CMS instance the client can reach over HTTPS (or HTTP on a local network).
Node.js 22 or later (the package's declared engines.node requirement) if the client itself needs to run npx — most desktop clients bundle their own Node runtime, so this mainly matters if you're invoking the server manually.
An Umbraco API user with the permissions you want the agent to have — see Umbraco's API user documentation. You'll come away with a client ID and client secret; treat the secret like a password (never commit it, never paste it into chat).

Coding Environments: `.mcp.json`

When the client is a coding agent working against a project (Claude Code, Cursor, VS Code, etc.), the preferred setup is a project-scoped MCP config file — e.g. .mcp.json for Claude Code — rather than a global/user-level config, so the server definition can be checked in and shared across the team without each developer's real secrets:

{
  "mcpServers": {
    "umbraco-mcp": {
      "command": "npx",
      "args": ["@umbraco-cms/mcp-dev@latest"],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "UMBRACO_CLIENT_ID": "your-api-user-id",
        "UMBRACO_CLIENT_SECRET": "your-api-secret",
        "UMBRACO_BASE_URL": "https://localhost:{port}",
        "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type"
      }
    }
  }
}

Keep real UMBRACO_CLIENT_ID / UMBRACO_CLIENT_SECRET values out of any file that gets committed — use a local, git-ignored env file or your client's secret-reference mechanism instead of hardcoding them in a checked-in .mcp.json.

Don't assume the @latest tag above for every project — the dist-tag depends on the target site's Umbraco major version. The two you'll hit most often:

@latest — Umbraco 18.x (current release)
@lts-17 — Umbraco 17.x (current LTS)

For anything older (@16 for 16.x, @alpha for the pre-16 package) or to confirm this mapping is still current, check the docs' Version Compatibility table.

Required and Optional Environment Variables

Env Var	Required	Description
`UMBRACO_CLIENT_ID`	Yes	OAuth client ID from the Umbraco API user
`UMBRACO_CLIENT_SECRET`	Yes	OAuth client secret — keep this out of chat, source control, and screenshots
`UMBRACO_BASE_URL`	Yes	Base URL of the Umbraco instance, e.g. `https://localhost:44391`
`NODE_TLS_REJECT_UNAUTHORIZED`	No	Set to `0` only for local instances with self-signed certs. Never set this for a production/public base URL.
`UMBRACO_INCLUDE_TOOL_COLLECTIONS`	No	Comma-separated collections to expose (e.g. `document,media`) — narrows the toolset the client loads
`UMBRACO_READONLY`	No	`true` removes all mutation tools — the LLM never sees them
`UMBRACO_DRY_RUN`	No	`true` lets mutation tools run and return a preview without calling the API
`UMBRACO_TOOL_MODES`	No	Comma-separated named modes — presets that enable a curated set of collections (see below)
`UMBRACO_INCLUDE_SLICES`	No	Comma-separated slices — only expose tools whose operation kind matches (see below)
`UMBRACO_EXCLUDE_SLICES`	No	Comma-separated slices to hide — takes precedence over `UMBRACO_INCLUDE_SLICES`

Slices and Modes

Beyond collections (document, media, etc.), the server supports two more ways to shape which tools a client sees:

A slice is the operation kind a tool performs (its verb), independent of which collection it belongs to. Every tool is tagged with one or more slices, so slice filtering cuts across collections — e.g. UMBRACO_INCLUDE_SLICES=read,search exposes only read/search tools across every enabled collection. Slices are defined in src/config/slice-registry.ts — the single source of truth; check that file for the current list rather than trusting a copy here (examples: create, read, update, delete, search, publish). Tools with no slices assigned fall back to other.

A mode is a named preset that maps to a fixed set of collections — a shortcut for "give me everything related to X" instead of listing collections by hand via UMBRACO_INCLUDE_TOOL_COLLECTIONS. Set UMBRACO_TOOL_MODES to a comma-separated list to enable more than one. Modes and what each one maps to are defined in src/config/mode-registry.ts — the single source of truth; check that file for the current list rather than trusting a copy here (examples: content, media, users, translation).

Modes, slices, and the collection/tool include-exclude filters all combine (exclude always wins over include) — e.g. UMBRACO_TOOL_MODES=content plus UMBRACO_EXCLUDE_SLICES=delete exposes every content-management tool except deletions.

For the CLI flag equivalents of these same env vars (--umbraco-tool-modes, --umbraco-include-slices, etc.) and the remaining filtering env vars (UMBRACO_INCLUDE_TOOLS, UMBRACO_EXCLUDE_TOOLS, UMBRACO_ALLOWED_MEDIA_PATHS, etc.), see the umb-cms-dev-cli skill's Tool Filtering and Runtime Modes tables rather than duplicating them here.

About this skill

Prerequisites

Coding Environments: .mcp.json

Required and Optional Environment Variables

Slices and Modes

Coding Environments: `.mcp.json`