@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

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.

Related MCP server: Remote MCP Server on Cloudflare

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

Limiting the tool surface

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

Available modes:

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

What you get

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

Contributing

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

License

MIT