Zitadel MCP Server

1# Zitadel MCP Server
2
3An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [Zitadel](https://zitadel.com/) identity management. Manage users, projects, applications, roles, and service accounts through natural language from AI tools like Claude Code.
4
5> *"Create a user for jane@example.com, assign her the app:finance role, and give me the auth config."*
6> — That's three tool calls the AI handles for you.
7
8## Tools (25)
9
10| Category | Tool | Description |
11|----------|------|-------------|
12| **Users** | `zitadel_list_users` | List/search users |
13| | `zitadel_get_user` | Get user details |
14| | `zitadel_create_user` | Create user (sends invite email) |
15| | `zitadel_deactivate_user` | Deactivate user |
16| | `zitadel_reactivate_user` | Reactivate user |
17| **Projects** | `zitadel_list_projects` | List projects |
18| | `zitadel_get_project` | Get project details |
19| | `zitadel_create_project` | Create project |
20| **Applications** | `zitadel_list_apps` | List apps in a project |
21| | `zitadel_get_app` | Get app details + Client ID |
22| | `zitadel_create_oidc_app` | Create OIDC application |
23| | `zitadel_update_app` | Update app (redirect URIs, etc.) |
24| **Roles** | `zitadel_list_project_roles` | List roles in a project |
25| | `zitadel_create_project_role` | Create a role (e.g., `app:finance`) |
26| | `zitadel_list_user_grants` | List user's role grants |
27| | `zitadel_create_user_grant` | Assign roles to user |
28| | `zitadel_remove_user_grant` | Remove role grant |
29| **Service Accounts** | `zitadel_create_service_user` | Create machine user |
30| | `zitadel_create_service_user_key` | Generate key pair |
31| | `zitadel_list_service_user_keys` | List keys (metadata only) |
32| **Organizations** | `zitadel_get_org` | Get current org details |
33| | `zitadel_list_orgs` | List organizations |
34| **Utility** | `zitadel_get_auth_config` | Get .env.local template for an app |
35| **Portal** | `portal_register_app` | Register app in portal DB |
36| | `portal_setup_full_app` | One-click: Zitadel + portal setup |
37
38Portal tools (`portal_*`) are only available when `PORTAL_DATABASE_URL` is configured.
39
40## Prerequisites
41
421. A Zitadel instance (Cloud or self-hosted)
432. A service account with **Org Owner** or **IAM Admin** role
443. A JSON key for the service account
45
46### Creating a Service Account
47
481. In the Zitadel Console, go to **Users** > **Service Users** > **New**
492. Give it a name (e.g., `mcp-admin`) and select **Bearer** token type
503. Go to the service user's **Keys** tab > **New** > **JSON**
514. Save the downloaded key file — you'll need the `userId`, `keyId`, and base64-encoded `key`
525. Grant the service account the **Org Owner** role under **Organization** > **Authorizations**
53
54## Setup
55
56```bash
57git clone https://github.com/takleb3rry/zitadel-mcp.git
58cd zitadel-mcp
59npm install
60npm run build
61```
62
63## Configuration
64
65Add the server to your MCP client config. The JSON block below works for both options:
66
67- **Global** (all projects): `~/.claude.json` under the `"mcpServers"` key
68- **Per-project**: `.mcp.json` in the project root
69
70```json
71{
72  "mcpServers": {
73    "zitadel": {
74      "command": "node",
75      "args": ["/path/to/zitadel-mcp/build/index.js"],
76      "env": {
77        "ZITADEL_ISSUER": "https://your-instance.zitadel.cloud",
78        "ZITADEL_SERVICE_ACCOUNT_USER_ID": "...",
79        "ZITADEL_SERVICE_ACCOUNT_KEY_ID": "...",
80        "ZITADEL_SERVICE_ACCOUNT_PRIVATE_KEY": "...",
81        "ZITADEL_ORG_ID": "...",
82        "ZITADEL_PROJECT_ID": "..."
83      }
84    }
85  }
86}
87```
88
89Restart Claude Code after adding the config. The Zitadel tools will appear automatically.
90
91### Environment Variables
92
93| Variable | Required | Description |
94|----------|----------|-------------|
95| `ZITADEL_ISSUER` | Yes | Zitadel instance URL |
96| `ZITADEL_SERVICE_ACCOUNT_USER_ID` | Yes | Service account user ID |
97| `ZITADEL_SERVICE_ACCOUNT_KEY_ID` | Yes | Key ID from the JSON key file |
98| `ZITADEL_SERVICE_ACCOUNT_PRIVATE_KEY` | Yes | Base64-encoded RSA private key (the `key` field from the downloaded JSON) |
99| `ZITADEL_ORG_ID` | Yes | Organization ID |
100| `ZITADEL_PROJECT_ID` | No | Default project ID for role operations |
101| `PORTAL_DATABASE_URL` | No | Postgres connection string (enables portal tools) |
102| `LOG_LEVEL` | No | `DEBUG`, `INFO`, `WARN`, `ERROR` (default: `INFO`) |
103
104## Security
105
106**This server has admin-level access to your Zitadel instance.** Understand what that means before using it:
107
108- 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.
109- 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.
110- 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.
111- All tool arguments containing PII (email, name, URLs) are **redacted from debug logs**. IDs and tool names are still logged.
112- All Zitadel IDs are validated against an alphanumeric format before being used in API paths.
113
114> **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.
115
116## Development
117
118```bash
119npm run dev    # Run with tsx (hot reload)
120npm run build  # Compile TypeScript
121npm start      # Run compiled version
122npm test       # Run tests
123```
124
125## License
126
127MIT
128