wp_list_users
Retrieve and filter WordPress users by role, search term, or activity status to manage site access and permissions.
Instructions
Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.
Usage Examples:
• List all users: wp_list_users
• Search users: wp_list_users --search="john"
• Filter by role: wp_list_users --roles=["editor","author"]
• Find admins: wp_list_users --roles=["administrator"]
• Combined search: wp_list_users --search="smith" --roles=["subscriber"]
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | The ID of the WordPress site to target (from mcp-wordpress.config.json). Required if multiple sites are configured. | |
| search | No | Limit results to those matching a search term. | |
| roles | No | Limit results to users with specific roles. |
Implementation Reference
- src/tools/users.ts:154-231 (handler)The main handler function that executes the wp_list_users tool. It fetches users using the WordPressClient, applies streaming for large lists, generates summaries and formatted output with roles, registration dates, and metadata.public async handleListUsers(client: WordPressClient, params: UserQueryParams): Promise<unknown> { try { const users = await client.getUsers(params); if (users.length === 0) { return "No users found matching the criteria."; } // Use streaming for large user result sets (>30 users) if (users.length > 30) { const streamResults: StreamingResult<unknown>[] = []; for await (const result of WordPressDataStreamer.streamUsers(users, { includeRoles: true, includeCapabilities: false, // Too verbose for large sets batchSize: 15, })) { streamResults.push(result); } return StreamingUtils.formatStreamingResponse(streamResults, "users"); } // Enhanced user information with comprehensive details const siteUrl = client.getSiteUrl ? client.getSiteUrl() : "Unknown site"; const userCount = users.length; const rolesSummary = users.reduce( (acc, u) => { const roles = u.roles || []; roles.forEach((role) => { acc[role] = (acc[role] || 0) + 1; }); return acc; }, {} as Record<string, number>, ); const metadata = [ `👥 **Users Summary**: ${userCount} total users`, `🌐 **Source**: ${siteUrl}`, `📊 **Roles Distribution**: ${Object.entries(rolesSummary) .map(([role, count]) => `${role}: ${count}`) .join(", ")}`, `📅 **Retrieved**: ${new Date().toLocaleString()}`, ]; const content = metadata.join("\n") + "\n\n" + users .map((u) => { const registrationDate = u.registered_date ? new Date(u.registered_date).toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric", }) : "Unknown"; const roles = u.roles?.join(", ") || "No roles"; const description = u.description || "No description"; const displayName = u.name || "No display name"; const userUrl = u.url || "No URL"; return ( `- **ID ${u.id}**: ${displayName} (@${u.slug})\n` + ` 📧 Email: ${u.email || "No email"}\n` + ` 🎭 Roles: ${roles}\n` + ` 📅 Registered: ${registrationDate}\n` + ` 🔗 URL: ${userUrl}\n` + ` 📝 Description: ${description}` ); }) .join("\n\n"); return content; } catch (_error) { throw new Error(`Failed to list users: ${getErrorMessage(_error)}`); } }
- src/tools/users.ts:29-52 (schema)The tool definition object specifying the name, description, input parameters schema (search string, roles array), and reference to the handler function.{ name: "wp_list_users", description: "Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.\n\n" + "**Usage Examples:**\n" + "• List all users: `wp_list_users`\n" + '• Search users: `wp_list_users --search="john"`\n' + '• Filter by role: `wp_list_users --roles=["editor","author"]`\n' + '• Find admins: `wp_list_users --roles=["administrator"]`\n' + '• Combined search: `wp_list_users --search="smith" --roles=["subscriber"]`', parameters: [ { name: "search", type: "string", description: "Limit results to those matching a search term.", }, { name: "roles", type: "array", items: { type: "string" }, description: "Limit results to users with specific roles.", }, ], handler: this.handleListUsers.bind(this),
- src/server/ToolRegistry.ts:46-62 (registration)Generic registration loop in ToolRegistry.registerAllTools() that instantiates UserTools (imported via * as Tools from '@/tools/index.js'), calls getTools() to retrieve the wp_list_users definition, and registers it with the MCP server via registerTool() which adds Zod validation and site selection.// Register all tools from the tools directory Object.values(Tools).forEach((ToolClass) => { let toolInstance: { getTools(): unknown[] }; // Cache and Performance tools need the clients map if (ToolClass.name === "CacheTools" || ToolClass.name === "PerformanceTools") { toolInstance = new ToolClass(this.wordpressClients); } else { toolInstance = new (ToolClass as new () => { getTools(): unknown[] })(); } const tools = toolInstance.getTools(); tools.forEach((tool: unknown) => { this.registerTool(tool as ToolDefinition); }); });
- src/index.ts:39-40 (registration)Calls ToolRegistry.registerAllTools() during server startup after creating the registry, which triggers registration of all tools including wp_list_users.private setupTools() { this.toolRegistry.registerAllTools();