Keycloak MCP Server

Instructions

Implementation Reference

• src/services/keycloak.ts:118-128 (handler)

  The core handler function that parses input arguments, fetches client roles from Keycloak Admin Client, and returns a formatted list.

  public async listClientRoles(args: unknown): Promise<string> {
    const { realm, clientUniqueId } = ListClientRolesSchema.parse(args);
    const roles: RoleRepresentation[] =
      await this.kcAdminClient.clients.listRoles({
        id: clientUniqueId,
        realm,
      });
    return `Roles in client ${clientUniqueId} in realm ${realm}:\n${roles
      .map((r) => `- ${r.name}`)
      .join("\n")}`;
  }

• src/schemas/index.ts:111-118 (schema)

  JSON schema definition for the 'list-client-roles' tool input, used in tool registration.

  "list-client-roles": {
    type: "object",
    properties: {
      realm: { type: "string" },
      clientUniqueId: { type: "string" },
    },
    required: ["realm", "clientUniqueId"],
  },

• src/server.ts:76-80 (registration)

  Tool registration in the ListTools response, including name, description, and input schema reference.

  {
    name: "list-client-roles",
    description: "List roles in a specific client",
    inputSchema: InputSchema["list-client-roles"],
  },

• src/server.ts:149-157 (handler)

  Dispatch handler in the CallToolRequest switch statement that invokes the KeycloakService handler.

  case "list-client-roles":
    return {
      content: [
        {
          type: "text",
          text: await keycloakService.listClientRoles(args),
        },
      ],
    };

• src/schemas/index.ts:41-44 (schema)

  Zod schema for input validation used within the handler.

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