wp_count_media: count media items
Returns how many attachments exist, broken down by MIME type. One call, no arguments.
Arguments
None.
Permissions
mcp:read and wp:content:read, with upload_files. Read-only, no write gate.
What it returns
A counts object keyed by MIME type — image/jpeg, image/png, application/pdf and so on — with the number of attachments of each.
What the breakdown tells you
More than a total would. The type distribution is a quick description of what the library actually contains:
- Mostly JPEG and PNG — a normal content site.
- A large PDF count — a documents library, and those are attachments MCP can read and delete but never create.
- Video or audio present — likewise outside what the upload tools accept.
- WebP or AVIF present — someone has been converting, or an optimisation plugin is generating them.
That last one is worth noticing before a bulk operation: a library where an optimisation plugin creates modern formats alongside originals has more attachment records than images.
Sizing a metadata job
The most common reason to call it. Before agreeing to "add alt text to the images":
Count the media, then list the first twenty and tell me how many are missing alt text.
The count sets the scale; the sample tells you the proportion needing work. Together they turn an open-ended request into a number.
For a large library the honest conclusion is often that an exhaustive pass is not worth it, and the right scope is the images on pages that matter. See Generate image metadata in bulk.
It counts what MCP cannot create
The counts include every attachment type in the library, not only the raster images the upload tools accept.
So a total here can exceed what MCP could ever have produced, and a type appearing in the counts does not mean an assistant can add more of it. See wp_upload_media for what is accepted.
Using it well
Count the media and show me the breakdown by type.
How many images are in the library?
At the start of an unfamiliar site:
Count the posts, pages and media, then stop.
Three read calls, and you know the shape of the site's content before agreeing to anything.
What it does not do
- No filtering. It counts everything.
- No total size in bytes. Disk usage is not reported.
- No count of unused attachments. Nothing here identifies orphans.
- No IDs. Use
wp_get_media.
The unused-attachment question comes up often and this tool cannot answer it. Neither can any other MCP tool: establishing that an attachment is unreferenced means checking post content, meta, theme settings and builder payloads, which is a job for a dedicated plugin.
Common problems
| Symptom | Cause |
|---|---|
pom_ai_mcp_forbidden |
The acting user lacks upload_files |
| Counts higher than expected | Generated format variants stored as separate attachments |
| Types you cannot upload | Correct; they were added another way |