WordPress media tool reference
Eight tools for the media library. They are the most constrained group in the server: uploads accept raster images only, and remote fetching is fenced in several ways at once.
The tools
| Tool | Does | Write |
|---|---|---|
wp_get_media |
List attachments | |
wp_get_media_item |
Read one attachment | |
wp_count_media |
Count attachments by type | |
wp_upload_media |
Upload from a base64 payload | Yes |
wp_upload_media_from_url |
Download a public URL and upload it | Yes |
wp_update_media |
Change title, caption, description or alt text | Yes |
wp_set_featured_image |
Assign or remove a featured image | Yes |
wp_delete_media |
Delete an attachment | Yes |
Permissions
Reading anything requires the upload_files capability — including listings and counts. Unlike posts, there is no unauthenticated read of published media through these tools.
Writes additionally need Allow content writes open, plus:
| Tool | Capability |
|---|---|
| Uploads | upload_files |
| Update | edit_post on the attachment |
| Set featured image | edit_post on the target post, not the attachment |
| Delete | delete_post on the attachment |
Scopes throughout: mcp:read and wp:content:read, plus mcp:write and wp:content:write for the writes.
Images only, verified twice
Uploads accept JPEG, PNG, GIF, WebP and AVIF and nothing else. No PDFs, no video, no audio, no SVG, no archives.
The check runs twice: once on the filename extension, then again on the actual file contents after it is written to disk. A file whose name says .png and whose bytes say something else is rejected at the second check.
The two errors are distinguishable — pom_ai_mcp_media_extension_denied for the name, pom_ai_mcp_media_mime_denied for the contents.
The 10 MB ceiling
Both upload tools cap at 10 MB, and the URL tool also limits the download response to the same size.
The response shape
Every tool returning an attachment returns the same fields: id, title, url, mime_type, alt, caption, description and date.
Note what is absent: no dimensions, no file size, and no list of generated sizes. To check whether an image is large enough for a hero slot, you have to look at it, not at the response.
Dry runs
All five write tools support dry_run, and each reports something different:
| Tool | Reports |
|---|---|
| Upload from URL | The URL it would fetch |
| Upload | The sanitised filename and the decoded byte count |
| Update | The changes it would apply |
| Set featured image | The post and the thumbnail ID |
| Delete | The ID it would delete |
The upload dry run is the useful one: it decodes the payload and reports the real size without writing anything, which catches a truncated base64 string before it becomes a failed upload.
The one that is not recoverable
Deleting an attachment is not undone by the WordPress trash the way a post is. Read wp_delete_media before using it.
Related
- Upload and assign a featured image
- Write alternative text that helps
- Image tools for POM AI's own image generation, which is separate from MCP