# Umbraco-CMS-MCP-Dev

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 39
- Author: umbraco
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/umbraco/Umbraco-CMS-MCP-Dev
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/umbraco-cms-mcp-dev

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `UMBRACO_CLIENT_ID`, `UMBRACO_CLIENT_SECRET`, `UMBRACO_BASE_URL`, `UMBRACO_INCLUDE_TOOL_COLLECTIONS`, `UMBRACO_READONLY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-dev
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-dev
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-dev
```
Replace <…> with your own values

## When to use it
- 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_READONLY` flag
- route requests to Umbraco Cloud projects via Cloudflare Workers

## Example prompts
- Inspect all document types configured in the current Umbraco site.
- Create a document using the `blogPost` type under the news section.
- Upload the logo asset directly into the media collection.

## Similar
- [emdash-cms](https://affpapa.org/en/nevibecode/skills/emdash-cms.md) — skill · 719 installs
- [cms-migration](https://affpapa.org/en/nevibecode/skills/cms-migration.md) — skill · 1900 installs
- [hyva-cms-custom-field](https://affpapa.org/en/nevibecode/skills/hyva-cms-custom-field.md) — skill · 752 installs
- [Total CMS](https://affpapa.org/en/nevibecode/mcp/total-cms.md) — MCP server · ★ 10
- [experience-cms-brand-apply](https://affpapa.org/en/nevibecode/skills/experience-cms-brand-apply.md) — skill · 5000 installs
- [webflow-mcp:cms-best-practices](https://affpapa.org/en/nevibecode/skills/webflow-mcpcms-best-practices.md) — skill · 877 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md