@umbraco-automate/mcp-dev

An MCP server for Umbraco Automate. Point it at an Umbraco instance and your AI assistant can build and publish automations, wire up their steps and triggers, manage connections and workspaces, inspect and control runs, handle approvals, and roll back to earlier versions — 62 Automate tools across 8 collections, plus a server-info tool.

Built on @umbraco-cms/mcp-server-sdk.

Requirements

• Node.js 22+
• An Umbraco instance with Umbraco Automate installed, reachable over HTTP(S)
• An API user on that instance (see below)

This version targets Umbraco 18 with Umbraco Automate 18.x. Connecting to a different major version warns and blocks the first tool call; set UMBRACO_EXPECTED_MAJOR to override if you know what you're doing.

Which version for which Umbraco

Umbraco	Umbraco Automate	Package
18	18.x	@umbraco-automate/mcp-dev
17	17.x	@umbraco-automate/mcp-dev@lts-17-beta

Install the version that matches your site's Umbraco major — the API client and the version check differ between them.

The Umbraco 17 line is in beta and published under the lts-17-beta dist-tag. A range such as @17 doesn't match prereleases and won't find a version until 17.0.0 is released.

1. Create an API user in Umbraco

In the Umbraco backoffice:

1. Go to Settings → Users
2. Create a new API user
3. Note its Client ID and Client Secret
4. Grant it permissions for the Automate sections you want the assistant to reach

The server authenticates with those credentials via OAuth client credentials.

2. Add it to your MCP client

Claude Code / Claude Desktop

Add to your .mcp.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "umbraco-automate": {
      "command": "npx",
      "args": ["-y", "@umbraco-automate/mcp-dev"],
      "env": {
        "UMBRACO_BASE_URL": "https://your-site.example.com",
        "UMBRACO_CLIENT_ID": "your-client-id",
        "UMBRACO_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart your client and the tools appear.

Any other MCP client

The server speaks MCP over stdio. Run it however your client spawns servers:

UMBRACO_BASE_URL=https://your-site.example.com \
UMBRACO_CLIENT_ID=your-client-id \
UMBRACO_CLIENT_SECRET=your-client-secret \
npx -y @umbraco-automate/mcp-dev

Local Umbraco with a self-signed certificate

Add "NODE_TLS_REJECT_UNAUTHORIZED": "0" to env. Only do this against local development instances — it disables certificate verification process-wide.

3. Check it works

Without wiring up a client:

# List every tool this server exposes
npx -y @umbraco-automate/mcp-dev --list-tools

# Show resolved configuration and where each value came from
npx -y @umbraco-automate/mcp-dev --debug-config

# Call a tool directly
UMBRACO_BASE_URL=... UMBRACO_CLIENT_ID=... UMBRACO_CLIENT_SECRET=... \
  npx -y @umbraco-automate/mcp-dev --call list-automations --call-args '{}'

--describe-tool <name> prints a single tool's full input schema.

Configuration

Every option is an environment variable, and most also have a CLI flag (--help lists them).

Connection

Variable	Required	Purpose
UMBRACO_BASE_URL	yes	Base URL of your Umbraco instance
UMBRACO_CLIENT_ID	yes	API user's client ID
UMBRACO_CLIENT_SECRET	yes	API user's client secret
UMBRACO_EXPECTED_MAJOR	no	Override the expected Umbraco major version

Limiting the tool surface

63 tools is a lot of context. Narrow it down:

Variable	Purpose
UMBRACO_TOOL_MODES	Enable named groups of collections (see below)
UMBRACO_INCLUDE_TOOL_COLLECTIONS	Only these collections
UMBRACO_EXCLUDE_TOOL_COLLECTIONS	Everything except these
UMBRACO_INCLUDE_TOOLS / UMBRACO_EXCLUDE_TOOLS	Individual tools by name
UMBRACO_INCLUDE_SLICES / UMBRACO_EXCLUDE_SLICES	By operation type, e.g. delete
UMBRACO_READONLY	Block every write operation
UMBRACO_DRY_RUN	Log writes instead of performing them

Available modes:

Mode	Includes
automate	All 8 Automate collections
umbraco-server	Server information only

"env": {
  "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "automations,catalogue,runs",
  "UMBRACO_READONLY": "true"
}

What you get

Collection	Tools	What it covers
automations	23	Create, publish, trigger, import/export and delete automations; add, connect and configure steps; set triggers
workspaces	10	Workspaces and the groups (folders) that organise automations
catalogue	8	Available triggers, actions, control flows, connection types, notification channels and webhook authenticators
connections	6	Stored credentials/endpoints that steps use, including a connection test
runs	6	Run history and detail; replay, resume, suspend and terminate runs
version-history	5	Past versions of an entity — list, inspect, compare and roll back
approvals	2	Runs paused on an approval step, and approving/rejecting them
metrics	2	Run metrics overall and per automation
umbraco-server	1	Umbraco server information (version, runtime)

Run --list-tools for the full list with descriptions.

Building an automation

The usual order:

1. list-catalogue-triggers / list-catalogue-step-types — see what's available.
2. create-automation — creates an empty draft in a workspace.
3. set-automation-trigger, then add-automation-step and connect-automation-steps — build the graph one piece at a time.
4. publish-automation — make it live. trigger-automation starts a run by hand.

To copy an existing automation, use export-automation and then import-automation (check the payload first with validate-automation-import).

Umbraco CMS tools

By default this server also chains to @umbraco-cms/mcp-dev, exposing CMS tools (documents, media, members) alongside the Automate ones, prefixed cms-- (e.g. cms--get-document-by-id). It reuses the same credentials. The chained server is configured in src/config/mcp-servers.ts.

Set DISABLE_MCP_CHAINING=true to turn this off and run Automate tools only.

Troubleshooting

Symptom	Likely cause
401 on every tool	Wrong UMBRACO_CLIENT_ID / UMBRACO_CLIENT_SECRET, or the API user lacks permissions
Self-signed certificate errors	Local HTTPS instance — set NODE_TLS_REJECT_UNAUTHORIZED=0
Version mismatch warning, first tool call blocked	Instance isn't Umbraco 18 — use @umbraco-automate/mcp-dev@lts-17-beta for Umbraco 17, or set UMBRACO_EXPECTED_MAJOR
404 on Automate tools	Umbraco Automate isn't installed on the instance
A tool you expected isn't listed	Check UMBRACO_TOOL_MODES and the include/exclude variables with --debug-config

Contributing

Setting up the repo, running the demo Umbraco site and the test suites: see CONTRIBUTING.md.

License

MIT