Keycloak MCP Server

Instructions

Implementation Reference

• src/services/keycloak.ts:108-116 (handler)

  Executes the tool logic: parses arguments with ListGroupsSchema, queries Keycloak admin client for groups in the specified realm, and returns a formatted text list.

  public async listGroups(args: unknown): Promise<string> {
    const { realm } = ListGroupsSchema.parse(args);
    const groups: GroupRepresentation[] = await this.kcAdminClient.groups.find({
      realm,
    });
    return `Groups in realm ${realm}:\n${groups
      .map((g) => `- ${g.name} (${g.id})`)
      .join("\n")}`;
  }

• src/server.ts:143-148 (handler)

  Tool dispatcher in the CallToolRequestSchema handler that calls the KeycloakService.listGroups method.

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

• src/schemas/index.ts:104-110 (schema)

  InputSchema definition for 'list-groups' tool used in registration and validation.

  "list-groups": {
    type: "object",
    properties: {
      realm: { type: "string" },
    },
    required: ["realm"],
  },

• src/server.ts:72-75 (registration)

  Registers the 'list-groups' tool in the ListToolsRequestSchema response.

    name: "list-groups",
    description: "List groups in a specific realm",
    inputSchema: InputSchema["list-groups"],
  },

• src/schemas/index.ts:37-39 (schema)

  Zod schema used for input validation inside the listGroups handler.

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