# Umbraco MCP

> Umbraco MCP Server gives your AI agent full control over Umbraco CMS content and media. You can list public pages, create drafts in the backoffice, update existing documents, or pull specific assets—all using natural conversation. It handles everything from structured data retrieval to binary file management without you touching a GUI.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** cms, content-delivery, media-management, asp-net, backoffice-automation, structured-content

## Description

Listen up. This Umbraco MCP Server gives your AI agent full control over the entire CMS content and media stack. You don't gotta touch the GUI or wrestle with dashboards—your agent handles everything using natural conversation.

Here’s how you use it:

**Content Retrieval & Publishing:** 
*   You can pull up specific, published content pieces by knowing their exact URL path; for instance, if someone hits `/products/new-feature`, your agent pulls that whole article. If you know the unique GUID or numeric ID of a live piece, it grabs that too using the Delivery API.
*   Want to see everything public? Your agent lists all available content through the Delivery API and handles pagination so you don't miss anything in large sites.
*   You can filter down massive datasets by type—say, pulling only entries where `contentType:blogPost` exists. This tool uses advanced query syntax specific to Umbraco’s Delivery API, letting your agent search like a pro.

**Backoffice Drafting & Management:** 
*   Need to work on something that isn't ready for the public? Your agent fetches drafts or non-published documents directly from the Umbraco backoffice using the Management API. This means you can review content before it ever hits the live site.
*   If you gotta make a new document draft, your agent builds it for you. It creates brand new documents in the CMS by accepting structured data via JSON and making sure that payload adheres to the required schema definition.
*   When an existing document needs a tweak, your agent updates those fields for you. You just give it the ID and a JSON object containing only the changes you want, and it pushes them live.
*   Sometimes, content gotta go. Your agent permanently deletes any draft or published document in Umbraco; remember, this action is irreversible.

**Schema and Asset Control:** 
*   You can check out every single Document Type (schema) used across the site by calling a list of all available schemas tool. This gives you a complete map of your content structure.
*   For media management, your agent lists every asset—images, PDFs, whatever—stored in the Umbraco Media library. It's like getting a full inventory count of everything attached to the CMS.

Basically, it lets your AI client perform all the standard CRUD operations right inside the engine room. You tell your agent what you need done—like 'find all product pages that reference the Q3 report' or 'create a draft for the updated privacy policy'—and it handles the back-end REST calls through both the public Delivery API and the private Management/Backoffice APIs. No more switching between an IDE, a terminal, and the CMS dashboard. Your agent manages it all.

## Tools

### create_cms_document
Creates a brand new document within the Umbraco CMS using provided JSON data and adhering to defined schemas.

### delete_cms_document
Permanently removes an existing document from the Umbraco CMS. This action cannot be undone.

### get_delivery_content_by_id
Retrieves a specific published content item using its unique GUID or numeric ID via the Delivery API.

### get_delivery_content_by_path
Fetches a specific piece of published content by knowing its exact URL path (e.g., '/contact').

### get_management_document
Retrieves drafts or non-published documents directly from the Umbraco backoffice using the Management API.

### list_delivery_content
Lists content available through the Delivery API, supporting pagination when dealing with large datasets.

### list_document_types
Provides a full list of all document types (schemas) defined and used within your Umbraco site.

### list_media_assets
Lists every media asset, such as images or files, stored in the Umbraco Media library.

### query_delivery_content
Filters and searches content items using advanced query syntax specific to the Umbraco Delivery API.

### update_cms_document
Updates fields of an existing document in Umbraco by providing its ID and a JSON object containing the changes.

## Prompt Examples

**Prompt:** 
```
Use the delivery API to get the content from '/products/new-feature' and list out its properties.
```

**Response:** 
```
I've pulled the content assigned to that path. It's a 'ProductPage' schema. Key properties include 'title' (New Feature Launch!) and strongly typed 'descriptionText'. Everything mapped perfectly fine over the Headless engine.
```

**Prompt:** 
```
Look up our Document Types to see the exact schema required for a 'BlogPost'. Then create one JSON draft placeholder payload based on it.
```

**Response:** 
```
A 'BlogPost' document requires 3 fields: `authorName`, `publishDate`, and `bodyText`. I have inherently crafted the JSON payload for this structure matching your schema accurately so we can push it cleanly up the line.
```

**Prompt:** 
```
Delete the backoffice document holding ID d6ef43...
```

**Response:** 
```
Done. The document d6ef43... has been successfully nuked from the active Umbraco Management context.
```

## Capabilities

### Fetch Content by URL Path
Retrieves a specific published piece of content using only its full web path, like `/products/new-feature`.

### List All Available Schemas
Grabs a complete list of every Document Type (schema) defined in your Umbraco environment.

### Create Backoffice Drafts
Pushes new document drafts into the CMS by providing structured data as a JSON object.

### Bulk Update Content Fields
Modifies specific fields of an existing Umbraco document using its ID and updated JSON data.

### Delete CMS Documents
Permanently removes a draft or published document from the Umbraco system.

### Query Content by Type
Filters and lists content items using specialized query syntax, such as finding all entries with `contentType:blogPost`.

## Use Cases

### Need to audit all product schema types.
A Platform Engineer needs to know if a new product line requires a 'ProductVariant' type. Instead of clicking through the CMS administration, they ask their agent to run `list_document_types`. The agent replies with an immediate list, letting them verify the exact schema name needed for coding.

### Correcting a typo on a live page.
A Digital Editor spots a title error on `/about-us`. They ask their agent to use `get_delivery_content_by_path` first, confirming the current content and ID. Then, they instruct the agent to use `update_cms_document`, providing only the JSON payload with the corrected text.

### Building a data migration script.
A Frontend Architect needs all old blog post contents for a new site build. They ask their agent to run `query_delivery_content` filtered by `contentType:blogPost`, getting structured JSON payloads ready to map directly into the headless application.

### Clean up outdated drafts.
A CMS Admin wants to delete a batch of obsolete documentation. They ask their agent to list all documents via `list_delivery_content` (using pagination), identify the specific GUIDs, and then run `delete_cms_document` on each one.

## Benefits

- **Full Lifecycle Control:** Don't just read data. Use `create_cms_document` to push new drafts or `update_cms_document` to modify existing fields without logging into the CMS GUI.
- **Targeted Retrieval:** Forget general searches. Fetch content using its exact path (`get_delivery_content_by_path`) or query only by schema type (`query_delivery_content`).
- **Schema Awareness:** Use `list_document_types` to know exactly what data structures exist before you try to populate a payload, saving hours of guesswork.
- **Media Asset Inventory:** Need to track every image? Run `list_media_assets` to get an absolute list of all binary files stored in the Umbraco library.
- **Draft Management:** Access non-published content using `get_management_document`, allowing your agent to work with drafts before they ever hit production.

## How It Works

The bottom line is: your AI client talks to Umbraco directly using defined API functions, skipping any manual UI steps entirely.

1. First, you subscribe to the Umbraco MCP server on Vinkius and inject your required Umbraco Base URL and Management Auth Token.
2. Second, you ask your AI client (e.g., Cursor) to perform an action—like 'list all media assets' or 'create a draft for the About page'.
3. The agent translates that request into specific tool calls (`list_media_assets` or `create_cms_document`), executes them against Umbraco, and returns the structured data.

## Frequently Asked Questions

**How do I get a draft document using get_management_document?**
You use this tool to retrieve drafts or non-published content that isn't visible via the standard Delivery API. You must specify the document ID and provide your management credentials.

**Can I bulk create multiple documents with create_cms_document?**
Yes, you supply a list of JSON objects to the tool call. The agent processes them one by one, creating multiple new drafts or structured records in Umbraco.

**What's the difference between get_delivery_content_by_id and query_delivery_content?**
`get_delivery_content_by_id` retrieves one item when you know its GUID. `query_delivery_content` is for searching—it filters a large set of content items based on criteria like content type or author.

**How do I update fields using update_cms_document?**
You pass the document's ID and then provide a JSON payload. The keys in your JSON must match the actual field names defined by the schema for that document type.

**When using list_delivery_content, how do I fetch content beyond the first page?**
You must manage pagination using the `take` and `skip` parameters. Send a request with a smaller batch size (e.g., take=50) and increment the skip value on successive calls to iterate through all available items.

**Before I use create_cms_document, how do I find out what content schemas exist?**
You need to run `list_document_types`. This tool returns a complete catalog of every document type (schema) configured in Umbraco. Use this list to ensure your JSON payload matches the required structure.

**What is the primary use case for list_media_assets?**
This tool pulls metadata on all binary assets—images and files—stored in the media library. It doesn't touch content; it gives you a comprehensive inventory of your media resources.

**If I run delete_cms_document, is there any way to recover that data?**
No. This action permanently removes the document from the Umbraco CMS context and cannot be undone by the AI agent or through subsequent API calls. Be certain of your target ID before executing it.

**Can it easily retrieve the content of a page assuming I only know its URL path?**
Absolutely. Instruct the agent to 'get_delivery_content_by_path' and supply something like '/home/about'. It traverses the Delivery API native routing map and returns perfectly all inner block grids and content variables attached.

**How do I ensure the JSON payloads for `create_cms_document` are exactly what Umbraco expects?**
Use the agent to first run 'list_document_types'. It pulls down the global schema blueprints. The LLM can explicitly read the allowed field types (like rich text or media pickers) and logically construct the insertion matching it exactly.

**Does it pull media details dynamically?**
Yes. Pinging 'list_media_assets' grants full insight over all stored visuals inside your Umbraco media containers, returning URL addresses alongside fundamental dimension formats so the agent can reference them anywhere.