wp_get_media: listar medios
Enumera los archivos adjuntos de la biblioteca de medios, opcionalmente filtrados por tipo MIME.
Argumentos
| Argumento | Predeterminado | Significado |
|---|---|---|
page |
1 | Número de página |
per_page |
20 | Elementos por página, limitado a 1–100 |
mime_type |
— | Filtrar por tipo MIME |
Permisos
mcp:read y wp:content:read, con la capacidad upload_files.
Ese requisito de capacidad se aplica a la lectura, no solo a la subida. Un token cuyo usuario no puede subir archivos no puede siquiera listar la biblioteca de medios — a diferencia de las entradas, donde el contenido publicado es legible sin ninguna capacidad.
Qué devuelve
items y total. Cada elemento lleva id, title, url, mime_type, alt, caption, description y date.
Sin dimensiones, sin tamaño de archivo
La respuesta no informa de las dimensiones de la imagen, del tamaño de archivo ni de qué tamaños generados existen.
Eso importa cuando la pregunta es «¿es esta imagen lo bastante grande para el hueco del hero?» — el listado no puede responderla. Tienes que abrir el url.
Filtrar por tipo MIME
mime_type acepta un tipo completo o un prefijo:
Lista los medios filtrados a
image/jpeg.
Lista los medios filtrados a
image.
La segunda forma es la útil en una biblioteca mixta, y conviene recordar que la biblioteca puede contener tipos que las herramientas de subida rechazarían. Los PDF y vídeos subidos a través del administrador de WordPress aparecen listados aquí; simplemente no pueden crearse a través de MCP.
Encontrar imágenes que necesitan trabajo
El uso real más común es encontrar archivos adjuntos con metadatos ausentes. El listado devuelve alt, caption y description, de modo que un asistente puede identificar las carencias:
Lista los medios y dime qué elementos tienen el texto alternativo vacío.
Esa es una auditoría de solo lectura, y produce la lista de IDs para una pasada posterior de wp_update_media.
La paginación importa más aquí
Las bibliotecas de medios suelen ser mucho más grandes que los recuentos de páginas. Con per_page limitado a 100, una biblioteca de varios miles requiere muchas llamadas.
Lee la total primero y decide si el trabajo merece hacerse de forma exhaustiva:
Lista los medios y dime el total, y luego detente.
Para una biblioteca grande, prioriza los archivos adjuntos realmente usados en páginas importantes en lugar de recorrerlo todo. Consulta Generar metadatos de imágenes en lote, que plantea el mismo argumento para la propia herramienta de metadatos de POM AI.
Sin ordenación ni búsqueda
No hay argumento de ordenación ni término de búsqueda. Los resultados siguen el orden predeterminado de la consulta, que es el más reciente primero.
Para encontrar un archivo adjunto concreto por nombre, recorre las páginas o usa el administrador de WordPress. Para encontrar los archivos adjuntos usados por una entrada específica, lee la entrada.
Usarlo bien
Lista los 20 archivos adjuntos más recientes con sus IDs, títulos y texto alternativo.
¿Cuántos archivos adjuntos hay en total?
Lista las imágenes y dime cuáles no tienen título de imagen (caption).
Problemas comunes
| Síntoma | Causa |
|---|---|
pom_ai_mcp_forbidden |
El usuario que actúa carece de upload_files |
| Menos elementos de los esperados | per_page se limita a 100; lee total |
| Aparecen tipos que no son imágenes | Correcto; la biblioteca puede contener lo que MCP no puede subir |
| No hay dimensiones en la respuesta | No forman parte de la estructura |
| Falta un archivo adjunto | Puede pertenecer a un sitio distinto de una red multisitio |