list-users
Retrieve all registered Clerk users with pagination controls to manage user lists efficiently.
Instructions
Lista todos os usuários cadastrados no Clerk com paginação
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| orderBy | No | created_at |
Implementation Reference
- src/clerk-tools.ts:32-73 (handler)Core handler function that implements the list-users tool logic: fetches users from Clerk API, maps the response, and returns formatted data with pagination info.export async function listUsers(params: { limit?: number; offset?: number; orderBy?: 'created_at' | 'updated_at'; }) { try { const { limit = 10, offset = 0, orderBy = 'created_at' } = params; const response = await clerk.users.getUserList({ limit, offset, orderBy: orderBy === 'created_at' ? '-created_at' : '-updated_at' }); const users = response.data.map(user => ({ id: user.id, email: user.emailAddresses[0]?.emailAddress || null, firstName: user.firstName, lastName: user.lastName, username: user.username, createdAt: user.createdAt, updatedAt: user.updatedAt, locked: user.locked, banned: user.banned })); return { success: true, data: { users, total: response.totalCount, limit, offset } }; } catch (error: any) { return { success: false, error: error.message || 'Erro ao listar usuários' }; } }
- src/clerk-tools.ts:15-19 (schema)Zod schema defining the input parameters for the list-users tool (limit, offset, orderBy).export const listUsersSchema = { limit: z.number().min(1).max(100).optional().default(10), offset: z.number().min(0).optional().default(0), orderBy: z.enum(['created_at', 'updated_at']).optional().default('created_at') };
- src/server.ts:27-61 (registration)Registration of the 'list-users' tool in the HTTP MCP server, specifying title, description, input/output schemas, and a thin wrapper around the handler.server.registerTool( 'list-users', { title: 'Listar Usuários', description: 'Lista todos os usuários cadastrados no Clerk com paginação', inputSchema: listUsersSchema, outputSchema: { success: z.boolean(), data: z.object({ users: z.array(z.object({ id: z.string(), email: z.string().nullable(), firstName: z.string().nullable(), lastName: z.string().nullable(), username: z.string().nullable(), createdAt: z.number(), updatedAt: z.number(), locked: z.boolean(), banned: z.boolean() })), total: z.number(), limit: z.number(), offset: z.number() }).optional(), error: z.string().optional() } }, async (params) => { const result = await listUsers(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result }; } );
- src/server-stdio.ts:26-60 (registration)Registration of the 'list-users' tool in the STDIO MCP server, identical to the HTTP version.server.registerTool( 'list-users', { title: 'Listar Usuários', description: 'Lista todos os usuários cadastrados no Clerk com paginação', inputSchema: listUsersSchema, outputSchema: { success: z.boolean(), data: z.object({ users: z.array(z.object({ id: z.string(), email: z.string().nullable(), firstName: z.string().nullable(), lastName: z.string().nullable(), username: z.string().nullable(), createdAt: z.number(), updatedAt: z.number(), locked: z.boolean(), banned: z.boolean() })), total: z.number(), limit: z.number(), offset: z.number() }).optional(), error: z.string().optional() } }, async (params) => { const result = await listUsers(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result }; } );