Zitadel

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.

"Create a user for [email protected], assign her the app:finance role, and give me the auth config." — That's three tool calls the AI handles for you.

Tools (25)

Category	Tool	Description
Users	zitadel_list_users	List/search users
	zitadel_get_user	Get user details
	zitadel_create_user	Create user (sends invite email)
	zitadel_deactivate_user	Deactivate user
	zitadel_reactivate_user	Reactivate user
Projects	zitadel_list_projects	List projects
	zitadel_get_project	Get project details
	zitadel_create_project	Create project
Applications	zitadel_list_apps	List apps in a project
	zitadel_get_app	Get app details + Client ID
	zitadel_create_oidc_app	Create OIDC application
	zitadel_update_app	Update app (redirect URIs, etc.)
Roles	zitadel_list_project_roles	List roles in a project
	zitadel_create_project_role	Create a role (e.g., app:finance)
	zitadel_list_user_grants	List user's role grants
	zitadel_create_user_grant	Assign roles to user
	zitadel_remove_user_grant	Remove role grant
Service Accounts	zitadel_create_service_user	Create machine user
	zitadel_create_service_user_key	Generate key pair
	zitadel_list_service_user_keys	List keys (metadata only)
Organizations	zitadel_get_org	Get current org details
	zitadel_list_orgs	List organizations
Utility	zitadel_get_auth_config	Get .env.local template for an app
Portal	portal_register_app	Register app in portal DB
	portal_setup_full_app	One-click: Zitadel + portal setup

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

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.

Environment Variables

Variable	Required	Description
ZITADEL_ISSUER	Yes	Zitadel instance URL
ZITADEL_SERVICE_ACCOUNT_USER_ID	Yes	Service account user ID
ZITADEL_SERVICE_ACCOUNT_KEY_ID	Yes	Key ID from the JSON key file
ZITADEL_SERVICE_ACCOUNT_PRIVATE_KEY	Yes	Base64-encoded RSA private key (the key field from the downloaded JSON)
ZITADEL_ORG_ID	Yes	Organization ID
ZITADEL_PROJECT_ID	No	Default project ID for role operations
PORTAL_DATABASE_URL	No	Postgres connection string (enables portal tools)
LOG_LEVEL	No	DEBUG, INFO, WARN, ERROR (default: INFO)

Security

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

• The service account needs Org Owner (or IAM Admin for zitadel_list_orgs). It can create users, modify roles, and manage applications in your organization.
• When you create an OIDC app (zitadel_create_oidc_app), the client secret is returned in the tool response. It is only available at creation time. The AI assistant (and its conversation history) will see it — save it immediately and treat it as sensitive.
• When you generate a service account key (zitadel_create_service_user_key), the full private key is returned in the tool response. Same caveat: save it, and be aware it's visible in your MCP client's 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: I've scanned all source files in this repo and found nothing notable, but I always recommend you have your own AI or tooling audit the code before installing any MCP server that gets access to your infrastructure. The full source is ~800 lines of TypeScript — a quick review shouldn't take long.

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