mcp-cli

Umbraco MCP Server — CLI Guide

Umbraco MCP servers built with @umbraco-cms/mcp-server-sdk run as CLI tools. You start the server with auth credentials and configuration flags, and it runs as an MCP server over stdio. Claude Code (or any MCP client) then connects and the LLM can call tools in an authenticated state.

How It Works

1. You run the CLI with auth credentials and optional configuration flags
2. The server authenticates against your Umbraco instance using OAuth client credentials
3. It starts an MCP server listening on stdin/stdout
4. Claude Code connects via MCP protocol and the LLM can call tools

The LLM never handles authentication — the CLI does that. The LLM just sees the tools and calls them.

Starting the Server

Via npx (published package)

npx @umbraco-cms/mcp-dev \
  --umbraco-client-id="your-client-id" \
  --umbraco-client-secret="your-secret" \
  --umbraco-base-url="https://localhost:44391"

Via built project

node dist/index.js \
  --umbraco-client-id="your-client-id" \
  --umbraco-client-secret="your-secret" \
  --umbraco-base-url="https://localhost:44391"

Via environment variables

UMBRACO_CLIENT_ID="your-client-id" \
UMBRACO_CLIENT_SECRET="your-secret" \
UMBRACO_BASE_URL="https://localhost:44391" \
node dist/index.js

Or use a .env file (loaded automatically) or specify a custom path with --env /path/to/.env.

CLI arguments take precedence over environment variables, which take precedence over .env file values.

Configuring Claude Code

Add the server to Claude Code's MCP configuration:

{
  "mcpServers": {
    "umbraco": {
      "command": "npx",
      "args": [
        "@umbraco-cms/mcp-dev",
        "--umbraco-client-id=your-client-id",
        "--umbraco-client-secret=your-secret",
        "--umbraco-base-url=https://localhost:44391"
      ]
    }
  }
}

For a locally built server:

{
  "mcpServers": {
    "umbraco": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "UMBRACO_CLIENT_ID": "your-client-id",
        "UMBRACO_CLIENT_SECRET": "your-secret",
        "UMBRACO_BASE_URL": "https://localhost:44391"
      }
    }
  }
}