Advanced Keycloak MCP server

Instructions

Implementation Reference

• src/index.ts:157-194 (handler)

  Core handler function in KeycloakService that authenticates, locates the client, fetches and returns its roles.

  async listRoles(realm: string, clientId: string) {
    await this.authenticate();
    this.client.setConfig({ realmName: realm });
  
    // Find the client by clientId (can be id or clientId string)
    let client = null;
    try {
      client = await this.client.clients.findOne({ realm, id: clientId });
    } catch {}
    
    if (!client) {
      const clients = await this.client.clients.find({ realm });
      client = clients.find(
        (c) => c.clientId === clientId || c.id === clientId
      );
    }
    
    if (!client) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        `Client '${clientId}' not found in realm '${realm}'.`
      );
    }
    
    if (!client.id || typeof client.id !== "string") {
      throw new McpError(
        ErrorCode.InvalidRequest,
        `Client found but has no valid id property.`
      );
    }
  
    const roles = await this.client.clients.listRoles({
      realm,
      id: client.id,
    });
  
    return { client, roles };
  }

• src/index.ts:397-408 (registration)

  Registers the 'list-roles' tool with MCP server including name, description, and JSON input schema.

  {
    name: "list-roles",
    description: "List all roles of a specific client in a specific realm",
    inputSchema: {
      type: "object",
      properties: {
        realm: { type: "string", description: "Realm name" },
        clientId: { type: "string", description: "Client ID" },
      },
      required: ["realm", "clientId"],
    },
  },

• src/index.ts:552-565 (handler)

  MCP tool call handler case that validates arguments, invokes service handler, and formats text response.

  case "list-roles": {
    const { realm, clientId } = ListRolesSchema.parse(args);
    const { client, roles } = await keycloakService.listRoles(realm, clientId);
    return {
      content: [
        {
          type: "text",
          text: `Roles for client '${client.clientId}' in realm '${realm}':\n${roles
            .map((r) => `- ${r.name}`)
            .join("\n")}`,
        },
      ],
    };
  }

• src/index.ts:471-474 (schema)

  Zod schema for input validation of list-roles tool parameters.

  const ListRolesSchema = z.object({
    realm: z.string(),
    clientId: z.string(),
  });