wp_list_media
Retrieve and filter media items from a WordPress site, enabling users to search, paginate results, and specify media types for efficient content management.
Instructions
Lists media items from a WordPress site, with filters.
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. | |
| per_page | No | Number of items to return per page (max 100). | |
| search | No | Limit results to those matching a search term. | |
| media_type | No | Limit results to a specific media type. |
Implementation Reference
- src/tools/media.ts:196-210 (handler)The handler function that implements the core logic of the wp_list_media tool. It queries the WordPress client for media items based on provided parameters, handles empty results, formats a markdown list of media items with IDs, titles, MIME types, and source URLs, and includes error handling.
public async handleListMedia(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> { const queryParams = params as MediaQueryParams; try { const media = await client.getMedia(queryParams); if (media.length === 0) { return "No media items found matching the criteria."; } const content = `Found ${media.length} media items:\n\n` + media.map((m) => `- ID ${m.id}: **${m.title.rendered}** (${m.mime_type})\n Link: ${m.source_url}`).join("\n"); return content; } catch (_error) { throw new Error(`Failed to list media: ${getErrorMessage(_error)}`); } } - src/tools/media.ts:68-90 (registration)The registration of the wp_list_media tool within the MediaTools.getTools() method, defining the tool name, description, input parameters schema, and binding the handler function. This object is returned by getTools() and registered dynamically by ToolRegistry.
{ name: "wp_list_media", description: "Lists media items from a WordPress site, with filters.", parameters: [ { name: "per_page", type: "number", description: "Number of items to return per page (max 100).", }, { name: "search", type: "string", description: "Limit results to those matching a search term.", }, { name: "media_type", type: "string", description: "Limit results to a specific media type.", enum: ["image", "video", "audio", "application"], }, ], handler: this.handleListMedia.bind(this), }, - src/tools/media.ts:71-88 (schema)The input schema definition for the wp_list_media tool parameters: per_page (number), search (string), media_type (string with enum). Used for validation in the MCP server.
parameters: [ { name: "per_page", type: "number", description: "Number of items to return per page (max 100).", }, { name: "search", type: "string", description: "Limit results to those matching a search term.", }, { name: "media_type", type: "string", description: "Limit results to a specific media type.", enum: ["image", "video", "audio", "application"], }, ],