zitadel-mcp

Purpose

Zitadel MCP Server is an MCP (Model Context Protocol) server for managing the Zitadel identity system in natural language through AI tools (such as Claude Code). It wraps the day-to-day management operations for users, projects, applications, roles, and service accounts as tool calls; for example, a single sentence "Provision jane@example.com as an Admin." can, in one tool call, create the user, assign the admin project role (v2 authorization), and grant ORG_USER_MANAGER so that they can manage other users, without any super admin involvement.

Main Capabilities

• Creation and management of users, projects, applications, roles, and service accounts.
• Implements a standardized two-role RBAC model: only the admin and standard project (business) roles, which are written into the OIDC token and control the user's permissions in the application; the configuration tool rejects other role keys to prevent drift.
• No-super-admin mode: every Admin also receives the organization-level ORG_USER_MANAGER authorization (managing Zitadel itself, not included in the token), so any Admin can create and manage users, including other Admins. It is recommended to keep at least two ORG_OWNER break-glass accounts for organization configuration.
• Role assignment prefers the v2 AuthorizationService (POST /v2/authorizations), and automatically falls back to v1 user-grants if the instance does not support it; organization administrator authorization uses the Management v1 org-member API.
• Login text management: supports overriding Login V2 i18n key-values via zitadel_set_hosted_login_translation (Settings v2 API); overrides are merged key by key onto the default texts; Login V1's Custom Login Texts are not wrapped by this server, because Login V2 completely ignores them.
• Portal tools (portal_*) are available only when PORTAL_DATABASE_URL is configured.
• zitadel_set_self_registration is available only when ZITADEL_ENABLE_LOGIN_POLICY_WRITE=true, and is disabled by default, because enabling self-registration makes all logins under that organization resolve to that organization's applications with public registration open, and the change leaves no user, authorization, or application records, making it hard to notice. The read-only zitadel_get_login_policy is always available.

How to Use

1. Prepare a Zitadel instance (Cloud or self-hosted).
2. Create a service account with the Org Owner or IAM Admin role: in the Zitadel Console, go to Users > Service Users > New, name it (e.g. mcp-admin), and select the Bearer token type; on the service user's Keys tab, create a new JSON key and save it; you will need the userId, keyId, and base64-encoded key from it; in Organization > Authorizations, grant the service account the Org Owner role.
3. Add the server to the MCP client configuration: the global configuration is under the "mcpServers" key in ~/.claude.json, and the project-level configuration is in .mcp.json in the project root. After adding it, restart Claude Code, and the Zitadel tools will appear automatically.
4. To avoid keys entering the MCP client configuration, you can omit the env block and put the variables in a .env file that is gitignored. The server reads the file specified by DOTENV_CONFIG_PATH, and next reads the .env in the repository root; variables already present in the process environment take precedence over both. DOTENV_CONFIG_PATH allows a globally installed binary to work without machine-specific paths.

Use Cases

• Quickly complete Zitadel user provisioning and role assignment through natural language.
• Manage organization users and permissions in no-super-admin mode.
• Manage OIDC applications, project roles, and service account keys.
• Override Login V2 login texts, for example to fix the confusing wrong-password prompt "Sitzung für Benutzer konnte nicht erstellt werden" (corresponding to Login V2 key password.errors.couldNotCreateSessionForUser).

Limitations and Security Considerations

• This server has admin-level access to the Zitadel instance. The service account requires organization-level management permissions: according to validation with Zitadel Cloud 2026-06, ORG_USER_MANAGER is sufficient to create users and assign existing project roles, but creating project roles, managing organization administrator authorizations (without super admin mode), and managing applications require ORG_OWNER. For full configuration workloads, it is recommended to give the service account ORG_OWNER, while the human Admin can remain ORG_USER_MANAGER.
• Secrets should be stored in a gitignored .env (rather than a shared dotfile), and ZITADEL_READ_ONLY=true can be used for non-mutating sessions.
• When creating an OIDC application (zitadel_create_oidc_app) as a confidential client, the client secret is not returned in the tool response and must be obtained from the Zitadel Console under Project → Apps → Configuration → Regenerate Client Secret.
• When generating a service account key (zitadel_create_service_user_key), the private key is written to ~/.zitadel-mcp/keys/ (file mode 600), and only the file path appears in the tool response.
• All tool parameters containing PII (email, name, URL) are redacted from debug logs, but IDs and tool names are still logged.
• All Zitadel IDs are validated for alphanumeric format before being used in API paths.
• It is recommended to audit the source code yourself before installing any MCP server that gains infrastructure administrator privileges, and to re-audit before every update.