Keycloak MCP Server

Instructions

Implementation Reference

• src/services/keycloak.ts:56-64 (handler)

  The main implementation of the list-users tool, which parses input arguments using ListUsersSchema, queries Keycloak for users in the specified realm, and returns a formatted list.

  public async listUsers(args: unknown): Promise<string> {
    const { realm } = ListUsersSchema.parse(args);
    const users: UserRepresentation[] = await this.kcAdminClient.users.find({
      realm,
    });
    return `Users in realm ${realm}:\n${users
      .map((u) => `- ${u.username} (${u.id})`)
      .join("\n")}`;
  }

• src/schemas/index.ts:16-18 (schema)

  Zod input schema for validating arguments in the listUsers handler (requires 'realm' string).

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

• src/schemas/index.ts:71-77 (schema)

  JSON Schema definition for list-users tool input, used in tool registration (requires 'realm' string).

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

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

  Registration of the list-users tool in the ListToolsRequestHandler response.

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

• src/server.ts:113-118 (handler)

  Handler dispatch in CallToolRequestHandler that calls the Keycloak service's listUsers method.

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