wp_get_media: list media
Lists attachments in the media library, optionally filtered by MIME type.
Arguments
| Argument | Default | Meaning |
|---|---|---|
page |
1 | Page number |
per_page |
20 | Items per page, clamped to 1–100 |
mime_type |
— | Filter by MIME type |
Permissions
mcp:read and wp:content:read, with the upload_files capability.
That capability requirement applies to reading, not just uploading. A token whose user cannot upload files cannot list the media library at all — unlike posts, where published content is readable without any capability.
What it returns
items and total. Each item carries id, title, url, mime_type, alt, caption, description and date.
No dimensions, no file size
The response does not report image dimensions, file size or which generated sizes exist.
That matters when the question is "is this image big enough for the hero slot?" — the listing cannot answer it. You have to open the url.
Filtering by MIME type
mime_type accepts a full type or a prefix:
List media filtered to
image/jpeg.
List media filtered to
image.
The second form is the useful one on a mixed library, and it is worth remembering that the library can contain types the upload tools would refuse. PDFs and video uploaded through the WordPress admin are listed here; they simply cannot be created through MCP.
Finding images that need work
The most common real use is finding attachments with missing metadata. The listing returns alt, caption and description, so an assistant can identify the gaps:
List the media and tell me which items have an empty alt text.
That is a read-only audit, and it produces the list of IDs for a subsequent wp_update_media pass.
Pagination matters more here
Media libraries are usually much larger than page counts. With per_page clamped to 100, a library of several thousand needs many calls.
Read the total first and decide whether the job is worth doing exhaustively:
List the media and tell me the total, then stop.
For a large library, prioritise the attachments actually used on important pages rather than working through everything. See Generate image metadata in bulk, which makes the same argument for POM AI's own metadata tool.
No ordering or search
There is no ordering argument and no search term. Results follow the query's default order, which is newest first.
To find a specific attachment by name, either page through or use the WordPress admin. To find attachments used by a specific post, read the post.
Using it well
List the 20 most recent attachments with their IDs, titles and alt text.
How many attachments are there in total?
List images and tell me which are missing captions.
Common problems
| Symptom | Cause |
|---|---|
pom_ai_mcp_forbidden |
The acting user lacks upload_files |
| Fewer items than expected | per_page clamps at 100; read total |
| Non-image types appear | Correct; the library can hold what MCP cannot upload |
| No dimensions in the response | Not part of the shape |
| An attachment is missing | It may belong to a different site of a multisite network |