umbraco Umbraco MCP Server — CLI Guide
This MCP server runs as a CLI tool over stdio. The CLI handles authentication and configuration, then exposes tools that talk directly to the Umbraco Management API.
Quick Reference
# List all tools
node dist/index.js --list-tools
# Describe a specific tool's schema
node dist/index.js --describe-tool <tool-name>
# Call a tool directly (requires auth via .env)
node dist/index.js --call <tool-name> --call-args '{"key":"value"}'
# Call a tool with a large/complex payload from a file (avoids shell/argv size limits)
node dist/index.js --call <tool-name> --call-args-file ./payload.json
# Generate context documentation
node dist/index.js --generate-context > CONTEXT.md
# Debug resolved configuration
node dist/index.js --debug-config
Authentication
Never pass secrets as CLI arguments. Use a .env file or the MCP config env block.
| Env Var | Required | Description |
|---|---|---|
UMBRACO_CLIENT_ID |
Yes | OAuth client ID from Umbraco API user |
UMBRACO_CLIENT_SECRET |
Yes | OAuth client secret |
UMBRACO_BASE_URL |
Yes | Umbraco instance URL |
Create a .env file:
UMBRACO_CLIENT_ID=your-client-id
UMBRACO_CLIENT_SECRET=your-secret
UMBRACO_BASE_URL=https://localhost:44391
Introspection commands (--list-tools, --describe-tool, --generate-context) do not require auth.
Starting the Server
# With .env file (recommended)
node dist/index.js
# Custom .env path
node dist/index.js --env /path/to/.env
Claude Code Configuration
Use the env block for credentials:
{
"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"
}
}
}
}
Tool Filtering
| Flag | Env Var | Description |
|---|---|---|
--umbraco-tool-modes |
UMBRACO_TOOL_MODES |
Enable named groups of collections |
--umbraco-include-slices |
UMBRACO_INCLUDE_SLICES |
Only expose tools with these slices |
--umbraco-exclude-slices |
UMBRACO_EXCLUDE_SLICES |
Hide tools with these slices |
--umbraco-include-tool-collections |
UMBRACO_INCLUDE_TOOL_COLLECTIONS |
Only expose these collections |
--umbraco-exclude-tool-collections |
UMBRACO_EXCLUDE_TOOL_COLLECTIONS |
Hide these collections |
--umbraco-include-tools |
UMBRACO_INCLUDE_TOOLS |
Only expose these specific tools |
--umbraco-exclude-tools |
UMBRACO_EXCLUDE_TOOLS |
Hide these specific tools |
Available slices: read, list, create, update, delete, search, tree, publish, move, copy.
Exclude takes precedence over include. Filters combine.
Runtime Modes
Readonly mode
node dist/index.js --umbraco-readonly
Mutation tools are completely removed — the LLM won't see them at all.
Dry-run mode
node dist/index.js --umbraco-dry-run
Read tools execute normally. Mutation tools return a preview without calling the API.
Introspection Commands
These print output and exit immediately — they do not start the MCP server.
| Flag | Description |
|---|---|
--list-tools |
Print ASCII table of all tools |
--describe-tool <name> |
Print full JSON schema for a tool |
--generate-context |
Output CONTEXT.md documenting all tools |
--debug-config |
Print resolved config (secrets masked) |
--call <name> |
Call a tool directly, print JSON result |
--call-args <json> |
JSON arguments for --call (default: {}) |
--call-args-file <path> |
Path to a file with JSON arguments for --call — use instead of --call-args for large/complex payloads (no shell size limits, safe for multiline JSON and non-ASCII). Cannot be combined with --call-args. |
Introspection respects all filtering. --list-tools with UMBRACO_READONLY=true shows exactly what the LLM would see.
Input Sanitization
The SDK validates all string inputs before tool handlers run:
- Rejects control characters, path traversal (
../), embedded query params, percent-encoded strings - Validates UUID format where expected
- Returns clear error messages for agent self-correction