wp_get_media_item: get one media item
Reads a single attachment by ID.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The attachment ID |
Permissions
mcp:read and wp:content:read, with upload_files.
What it returns
id, title, url, mime_type, alt, caption, description and date.
The same shape a listing returns — this tool exists to fetch one item by ID rather than to return more detail than the listing does.
The url is the useful field
Because the response carries no dimensions and no file size, the url is how you actually inspect the image. Open it.
That matters most after an upload: confirming an image arrived is not the same as confirming it is usable at the size you need. A 400-pixel-wide image uploaded for a full-width hero is a correct upload and a wrong outcome.
It only reads attachments
An ID that is not an attachment returns pom_ai_mcp_media_not_found, the same error as a missing ID. Passing a post ID by mistake produces "not found" rather than something clearer.
Confirm before assigning or deleting
Two operations take a media ID and act elsewhere, and both benefit from reading the item first:
Before setting a featured image, confirm the attachment is the one you mean:
Read media 1180 and show me its title and URL, then set it as the featured image for post 412.
Before deleting, confirm what you are removing — media deletion is not recoverable from the trash the way a post is. See wp_delete_media.
Reading back after an update
wp_update_media returns the updated record, but reading independently afterwards is worth it when several fields changed, because it shows the stored result rather than what was requested.
Update the alt text, then read media 1180 back.
Alt text is the field to look at
The alt field is where accessibility lives, and it is empty far more often than people expect — WordPress does not require it, and images uploaded in bulk rarely have it.
An empty alt on a decorative image is correct. An empty alt on an informative one is a real accessibility gap. The tool cannot tell you which is which; see Write alternative text that helps.
Using it well
Read media 1180 and show me every field.
Show me the current alt text and caption for media 1180 before changing them.
That second pattern gives you the old values, which is your only undo for a metadata change — attachments do not have revisions.
Common problems
| Symptom | Cause |
|---|---|
pom_ai_mcp_media_not_found |
Wrong ID, or the ID is not an attachment |
pom_ai_mcp_forbidden |
The acting user lacks upload_files |
| No dimensions in the response | Not part of the shape; open the url |
| The URL 404s | The file is missing from disk although the record exists |
That last case is worth knowing: WordPress can hold an attachment record whose file has been removed from the uploads directory. The record reads fine and the image is broken everywhere it appears.