Zitadel MCP

Zitadel MCP Server

An MCP (Model Context Protocol) server for Zitadel identity management. Manage users, projects, applications, roles, and service accounts through natural language from AI tools like Claude Code.

"Provision jane@example.com as an Admin." — One tool call: creates the user, assigns the admin project role (v2 authorization), and grants ORG_USER_MANAGER so she can manage other users — no Super Admin required.

Tools (37)

Portal tools (portal_*) are only available when PORTAL_DATABASE_URL is configured.

zitadel_set_self_registration is only available when ZITADEL_ENABLE_LOGIN_POLICY_WRITE=true. It is off by default because enabling self-registration opens the organization to public signup for every application whose login resolves to that org, and — unlike every other write tool here — the change leaves behind no user, grant, or app record that would make it noticeable. The read-only zitadel_get_login_policy is always available.

Two-role model & no-super-admin (Renewal Initiatives SSO)

The provisioning tools implement a standardized RBAC model for the core apps:

• Two project (business) roles only: admin and standard — these land in the OIDC token and gate what a user can do in the apps. The provisioning tools refuse any other key to prevent drift.
• No Super Admin: every Admin also receives an org-level ORG_USER_MANAGER grant (a manager role — administers Zitadel itself, not in the token), so any Admin can create/manage any user, including other Admins. Keep ≥2 ORG_OWNER break-glass accounts for org configuration.
• Role assignment prefers the v2 AuthorizationService (POST /v2/authorizations) and automatically falls back to v1 user-grants if that endpoint is unavailable on the instance (some Zitadel Cloud versions return 404). Org-manager grants use the Management v1 org-member API.

Login texts: Login V2 vs. the legacy Custom Login Texts

Zitadel has two login UIs with two unrelated text mechanisms — mixing them up is a common dead-end:

• Login V2 (the current default — instance feature loginV2.required, or per-app loginVersion.loginV2) is the TypeScript/hosted login. Its strings live in the login app's i18n bundles (apps/login/locales/<lang>.json in zitadel/zitadel). Override individual keys with zitadel_set_hosted_login_translation (Settings v2 API); overrides merge onto the shipped defaults key-by-key, so upstream fixes to untouched keys still flow through.
• Login V1 (legacy Angular login) reads the Management API Custom Login Texts (/management/v1/text/login/{lang}). Login V2 ignores those entirely (zitadel #8608), so this server deliberately does not wrap them.

Practical example — the confusing wrong-password message "Sitzung für Benutzer konnte nicht erstellt werden" is the Login V2 key password.errors.couldNotCreateSessionForUser (fallback when the password-check error carries no attempt counter). Fix it with:

zitadel_set_hosted_login_translation({
  locale: "de",
  translations: {
    "password.errors.couldNotCreateSessionForUser": "Benutzername oder Passwort falsch. Bitte versuchen Sie es erneut.",
    "loginname.errors.couldNotCreateSession": "Benutzername oder Passwort falsch. Bitte versuchen Sie es erneut."
  }
})

Prerequisites

1. A Zitadel instance (Cloud or self-hosted)
2. A service account with Org Owner or IAM Admin role
3. A JSON key for the service account

Creating a Service Account

1. In the Zitadel Console, go to Users > Service Users > New
2. Give it a name (e.g., mcp-admin) and select Bearer token type
3. Go to the service user's Keys tab > New > JSON
4. Save the downloaded key file — you'll need the userId, keyId, and base64-encoded key
5. Grant the service account the Org Owner role under Organization > Authorizations

Setup

git clone https://github.com/takleb3rry/zitadel-mcp.git
cd zitadel-mcp
npm install
npm run build

Configuration

Add the server to your MCP client config. The JSON block below works for both options:

• Global (all projects): ~/.claude.json under the "mcpServers" key
• Per-project: .mcp.json in the project root

{
  "mcpServers": {
    "zitadel": {
      "command": "node",
      "args": ["/path/to/zitadel-mcp/build/index.js"],
      "env": {
        "ZITADEL_ISSUER": "https://your-instance.zitadel.cloud",
        "ZITADEL_SERVICE_ACCOUNT_USER_ID": "...",
        "ZITADEL_SERVICE_ACCOUNT_KEY_ID": "...",
        "ZITADEL_SERVICE_ACCOUNT_PRIVATE_KEY": "...",
        "ZITADEL_ORG_ID": "...",
        "ZITADEL_PROJECT_ID": "..."
      }
    }
  }
}

Restart Claude Code after adding the config. The Zitadel tools will appear automatically.

To keep secrets out of the MCP client config, omit the env block and put the variables in a gitignored .env file instead. The server reads the file named by DOTENV_CONFIG_PATH if set, then the .env in the repo root. Variables already present in the process environment (e.g. from an env block) take precedence over both. DOTENV_CONFIG_PATH is what makes a globally installed binary work without machine-specific paths:

{
  "mcpServers": {
    "zitadel": {
      "command": "zitadel-mcp",
      "env": { "DOTENV_CONFIG_PATH": "/home/me/.config/zitadel-mcp/.env" }
    }
  }
}

Environment Variables

Security

This server has admin-level access to your Zitadel instance. Understand what that means before using it:

• The service account needs org-level management rights. Empirically (Zitadel Cloud, verified 2026-06): ORG_USER_MANAGER is enough to create users and assign existing project roles, but ORG_OWNER is required to create project roles, manage org-manager grants (the no-super-admin pattern), and manage applications. For the full provisioning workload, give the service account ORG_OWNER; human Admins can stay at ORG_USER_MANAGER. Keep the key in a gitignored .env (not a shared dotfile) and use ZITADEL_READ_ONLY=true for non-mutating sessions.
• When you create an OIDC app (zitadel_create_oidc_app) as a confidential client, the client secret is NOT returned in the tool response (so it never enters the AI conversation). Retrieve it from the Zitadel Console: Project → Apps → Configuration → Regenerate Client Secret.
• When you generate a service account key (zitadel_create_service_user_key), the private key is written to ~/.zitadel-mcp/keys/ (file mode 600) instead of being returned in the tool response — only the file path appears in the conversation.
• All tool arguments containing PII (email, name, URLs) are redacted from debug logs. IDs and tool names are still logged.
• All Zitadel IDs are validated against an alphanumeric format before being used in API paths.

Note for new users: always audit the source yourself (or with your own tooling) before installing any MCP server that gets admin access to your infrastructure — and re-audit every update before applying it. Do not take this README's word for it.

Development

npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript
npm start      # Run compiled version
npm test       # Run tests

License

MIT