Upload File to WordPress Media Library
wp_upload_mediaUpload a local file to the WordPress media library as a new attachment, returning the created media item with metadata.
Instructions
Upload a local file to the WP media library as a new attachment. Reads the file from file_path on the MCP host machine, sends as multipart/form-data, and returns the created media item.
Args:
file_path (string): Absolute path to the file on disk. Required.
title (string): Optional title (defaults to filename).
alt_text (string): Optional alt text.
caption (string): Optional caption.
description (string): Optional description.
post (number): Optional post/page ID to attach the media to (0 = unattached).
response_format (enum): markdown | json. Default 'markdown'.
Returns: The newly-created WPMediaItem with id, source_url, dimensions, etc.
Notes:
The MCP host process must have read access to file_path.
For best SEO, always pass alt_text on image uploads.
WP MIME-sniffs the file; the upload will be rejected if the extension is on WP's disallowed list (e.g. executables).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| post | No | Attach this media to a specific post/page ID. 0 (default) = unattached. | |
| title | No | Title for the media item. Defaults to the filename minus extension. | |
| caption | No | Caption shown beneath the image in some themes. | |
| alt_text | No | Alt text for accessibility. Strongly recommended for images. | |
| file_path | Yes | Absolute path to a local file to upload. Must be readable by the MCP process. (For files in your workspace folder, use the full Windows path.) | |
| description | No | Longer description (rendered on the attachment page). | |
| response_format | No | Output format: 'markdown' for human-readable, 'json' for machine-readable. | markdown |