Keycloak MCP Server

Instructions

Implementation Reference

• src/services/keycloak.ts:66-87 (handler)

  Core handler function that executes the tool logic: parses args, lists client roles, finds the role, assigns it to the user via Keycloak admin client, and returns success message.

  public async assignClientRoleToUser(args: unknown): Promise<string> {
    const { realm, userId, clientUniqueId, roleName } =
      AssignClientRoleSchema.parse(args);
    const roles: RoleRepresentation[] =
      await this.kcAdminClient.clients.listRoles({
        id: clientUniqueId,
        realm,
      });
    const role: RoleRepresentation | undefined = roles.find(
      (r) => r.name === roleName
    );
    if (!role || !role.id || !role.name) {
      throw new Error(`Role '${roleName}' not found or has no ID.`);
    }
    await this.kcAdminClient.users.addClientRoleMappings({
      realm,
      id: userId,
      clientUniqueId,
      roles: [{ id: role.id, name: role.name }],
    });
    return `Assigned role '${roleName}' to user ${userId} in client ${clientUniqueId}`;
  }

• src/server.ts:119-127 (handler)

  MCP server tool handler switch case that receives tool call and delegates to the KeycloakService method.

  case "assign-client-role-to-user":
    return {
      content: [
        {
          type: "text",
          text: await keycloakService.assignClientRoleToUser(args),
        },
      ],
    };

• src/schemas/index.ts:20-25 (schema)

  Zod schema used for input validation within the handler function.

  export const AssignClientRoleSchema = z.object({
    realm: z.string(),
    userId: z.string(),
    clientUniqueId: z.string(),
    roleName: z.string(),
  });

• src/schemas/index.ts:78-87 (schema)

  JSON schema definition for the tool input, used in MCP tool registration.

  "assign-client-role-to-user": {
    type: "object",
    properties: {
      realm: { type: "string" },
      userId: { type: "string" },
      clientUniqueId: { type: "string" },
      roleName: { type: "string" },
    },
    required: ["realm", "userId", "clientUniqueId", "roleName"],
  },

• src/server.ts:56-60 (registration)

  Tool registration in the MCP server's listTools response.

  {
    name: "assign-client-role-to-user",
    description: "Assign a client role to a user",
    inputSchema: InputSchema["assign-client-role-to-user"],
  },