用途
Zitadel MCP Server 是一个 MCP（Model Context Protocol）服务器，用于通过 AI 工具（如 Claude Code）以自然语言管理 Zitadel 身份系统。它把用户、项目、应用、角色和服务账号的日常管理操作封装为工具调用，例如一句“Provision jane@example.com as an Admin.”即可在一次工具调用中创建用户、分配 admin 项目角色（v2 授权）并授予 ORG_USER_MANAGER，使其能够管理其他用户，而无需超级管理员介入。
主要能力
- 用户、项目、应用、角色和服务账号的创建与管理。
- 实现标准化的双角色 RBAC 模型：仅 admin 和 standard 两个项目（业务）角色，会写入 OIDC token 并控制用户在应用中的权限；配置工具会拒绝其他角色键以防止漂移。
- 无超级管理员模式：每个 Admin 同时获得组织级 ORG_USER_MANAGER 授权（管理 Zitadel 本身，不进入 token），因此任何 Admin 都能创建和管理用户，包括其他 Admin。建议保留至少两个 ORG_OWNER 破窗账号用于组织配置。
- 角色分配优先使用 v2 AuthorizationService（POST /v2/authorizations），若实例不支持则自动回退到 v1 user-grants；组织管理员授权使用 Management v1 org-member API。
- 登录文案管理：支持通过 zitadel_set_hosted_login_translation（Settings v2 API）覆盖 Login V2 的 i18n 键值，覆盖会逐键合并到默认文案上；Login V1 的 Custom Login Texts 不被该服务器包装，因为 Login V2 完全忽略它们。
- 门户工具（portal_*）仅在配置了 PORTAL_DATABASE_URL 时可用。
- zitadel_set_self_registration 仅在 ZITADEL_ENABLE_LOGIN_POLICY_WRITE=true 时可用，默认关闭，因为开启自注册会使该组织下所有登录解析到该组织的应用开放公开注册，且该变更不会留下用户、授权或应用记录，不易察觉。只读的 zitadel_get_login_policy 始终可用。
使用方式
- 准备一个 Zitadel 实例（Cloud 或自托管）。
- 创建具有 Org Owner 或 IAM Admin 角色的服务账号：在 Zitadel Console 中进入 Users > Service Users > New，命名（如 mcp-admin）并选择 Bearer token 类型；在服务用户的 Keys 标签页新建 JSON 密钥并保存，需要其中的 userId、keyId 和 base64 编码的 key；在 Organization > Authorizations 中授予该服务账号 Org Owner 角色。
- 将服务器添加到 MCP 客户端配置：全局配置位于 ~/.claude.json 的 "mcpServers" 键下，项目级配置位于项目根目录的 .mcp.json。添加后重启 Claude Code，Zitadel 工具会自动出现。
- 为避免密钥进入 MCP 客户端配置，可省略 env 块，将变量放入被 gitignore 的 .env 文件。服务器会读取 DOTENV_CONFIG_PATH 指定的文件，其次读取仓库根目录的 .env；进程环境中已存在的变量优先于两者。DOTENV_CONFIG_PATH 可使全局安装的二进制无需机器特定路径即可工作。
适用场景
- 通过自然语言快速完成 Zitadel 用户开通与角色分配。
- 在无超级管理员模式下管理组织用户与权限。
- 管理 OIDC 应用、项目角色和服务账号密钥。
- 覆盖 Login V2 的登录文案，例如修复令人困惑的错误密码提示“Sitzung für Benutzer konnte nicht erstellt werden”（对应 Login V2 键 password.errors.couldNotCreateSessionForUser）。
限制与安全注意事项
- 该服务器对 Zitadel 实例具有管理员级访问权限。服务账号需要组织级管理权限：根据 Zitadel Cloud 2026-06 的验证，ORG_USER_MANAGER 足以创建用户和分配已有项目角色，但创建项目角色、管理组织管理员授权（无超级管理员模式）和管理应用需要 ORG_OWNER。完整配置工作负载建议给服务账号 ORG_OWNER，人类 Admin 可保持 ORG_USER_MANAGER。
- 密钥应保存在被 gitignore 的 .env 中（而非共享 dotfile），非变更会话可使用 ZITADEL_READ_ONLY=true。
- 创建 OIDC 应用（zitadel_create_oidc_app）为机密客户端时，客户端密钥不会在工具响应中返回，需从 Zitadel Console 的 Project → Apps → Configuration → Regenerate Client Secret 获取。
- 生成服务账号密钥（zitadel_create_service_user_key）时，私钥写入 ~/.zitadel-mcp/keys/（文件模式 600），工具响应中只出现文件路径。
- 所有包含 PII（邮箱、姓名、URL）的工具参数会从调试日志中脱敏，但 ID 和工具名仍会记录。
- 所有 Zitadel ID 在使用于 API 路径前都会进行字母数字格式校验。
- 建议在安装任何获得基础设施管理员权限的 MCP 服务器前自行审计源代码，并在每次更新前重新审计。
