WordPress Integration

Home > Documentation > WordPress Integration

Complete WordPress REST API integration with advanced media management capabilities.

Table of contents

  1. WordPress Integration
    1. Table of contents
    2. Overview
    3. Features
    4. 📝 Content Management
    5. 🖼️ Media Management
    6. 🔐 Security
    7. 🏷️ Category & Tag Management
    8. ⚙️ Advanced Features
    9. Configuration
    10. Setting up Application Passwords
    11. Available Tools
    12. Core Content Management
      1. create_post
      2. create_advanced_post
      3. create_post_with_embeds
      4. update_post
      5. delete_post
      6. Slugs
    13. Content Retrieval
      1. get_posts
      2. get_pages
      3. get_all_content
      4. get_post
    14. Media Management
      1. upload_media
      2. get_media
      3. get_media_item
      4. update_media
      5. delete_media
      6. create_post_with_featured_image
      7. set_featured_image
    15. Category & Tag Management
    16. get_post
    17. update_post
    18. delete_post
    19. get_comments
    20. get_categories
    21. create_category
    22. update_category
    23. delete_category
    24. get_tags
    25. create_tag
    26. update_tag
    27. delete_tag
    28. create_post_with_categories_tags
    29. update_post_categories_tags
    30. Site Settings
    31. get_settings
    32. update_settings
    33. set_front_page
    34. set_front_page_to_posts
    35. Workflow Examples
    36. Basic Blog Post
    37. Featured Image Workflow
    38. Update Existing Post
    39. Category Management Workflow
    40. Tag Management Workflow
    41. Smart Content Creation Workflow
    42. Complete Content Management Workflow
    43. Content Lifecycle Management
    44. AI-Assisted Taxonomy Management
    45. Error Handling
    46. Supported File Types
    47. Performance Optimization
    48. Troubleshooting
    49. Common Issues
    50. Debug Mode
    51. Health Check System
    52. wordpress_health_check
    53. Check Process
      1. 1. 🌐 Site Accessibility
      2. 2. 🔌 REST API Availability
      3. 3. 🔐 Authentication Validation
      4. 4. ✅ Permission Verification
      5. 5. 📁 Media Upload Capability
    54. Health Report
    55. Status Levels
    56. Troubleshooting Guide
      1. Site Accessibility Issues
      2. REST API Problems
      3. Authentication Failures
      4. Permission Issues
      5. Upload Problems
    57. Best Practices
      1. Before Production Use
      2. Production Operations
        1. Application Password Management
        2. Maintenance Mode Operations
        3. Production Monitoring
      3. Automated Monitoring
      4. Integration Workflow

Overview

MCP-RS provides comprehensive WordPress integration through the WordPress REST API, enabling AI agents to perform content management tasks with full featured image support.

Features

📝 Content Management

  • Advanced Post Creation: Create posts and pages with comprehensive options
  • Post Type Support: Both posts (blog articles) and pages (static content)
  • Status Control: Draft, publish, private, and scheduled posts
  • SEO Integration: Meta fields for Yoast SEO and other plugins
  • Post Retrieval: Get all published posts with metadata
  • Complete CRUD: Create, read, update, and delete operations
  • Comment Management: Retrieve and manage post comments

🖼️ Media Management

  • File Upload: Upload images, documents, and media files
  • Featured Images: Set and manage post featured images
  • Multiple Formats: Support for JPEG, PNG, GIF, PDF, and more
  • Base64 or Local Files: Upload base64-encoded data, or a local file from an allowed folder (upload_allowed_dirs)

🔐 Security

  • Application Passwords: Secure authentication with WordPress
  • Timeout Handling: Configurable request timeouts
  • Retry Logic: Automatic retry for transient failures (up to 3 attempts). Create and delete requests are not resent after a timeout or server error, since WordPress may already have processed them
  • Error Handling: Comprehensive error reporting

🏷️ Category & Tag Management

  • Category Operations: Create, read, update, and delete categories
  • Tag Operations: Create, read, update, and delete tags
  • Hierarchical Categories: Support for parent-child category relationships
  • Bulk Operations: Efficient management of multiple categories and tags

⚙️ Advanced Features

  • Structured API: Clean parameter structures for maintainable code
  • Flexible Updates: Partial updates with optional parameters
  • Meta Data Support: Custom fields and SEO metadata
  • Post Scheduling: Future publication with ISO8601 timestamps

Configuration

Add WordPress configuration to your mcp-config.toml:

[handlers.wordpress]
url = "https://your-wordpress-site.com"
username = "your_username"
password = "your_application_password"
enabled = true
timeout_seconds = 30

# Optional: tool calls are rate limited per WordPress site (defaults shown)
[handlers.wordpress.rate_limit]
requests_per_second = 10
burst_size = 20
enabled = true

enabled = true is required: without it, the WordPress tools are not registered (and ${...} is not expanded), with no error.

To keep the Application Password out of the config file in plaintext:

  • keyring = "<name>" instead of username/password: read them from the OS credential store (Windows Credential Manager, macOS Keychain, Secret Service). This works the same whether Claude Desktop, Claude Code, or a terminal starts mcp-rs. See OS Credential Store
  • ${WORDPRESS_PASSWORD}: read an environment variable. Claude Desktop passes only the variables in env of its JSON config. See Which environment variables reach mcp-rs
  • encrypted_credentials: see Encrypted WordPress Credentials

When enabled = true, one of username/password, keyring, or encrypted_credentials must be set, otherwise startup fails.

To let upload_media read local files with file_path, list the folders it may read from. It is disabled when the list is empty (the default). Startup fails if a listed folder does not exist.

[handlers.wordpress]
upload_allowed_dirs = ["C:/Users/me/Pictures/blog"]

Setting up Application Passwords

Create the Application Password for a WordPress user with only the role the AI client needs, preferably a dedicated user:

Role What the AI client can do Use when
Contributor Write and edit its own drafts. Cannot publish, and cannot upload media You review and publish every post yourself
Author Also publish its own posts and upload media You want the AI client to publish
Editor, Administrator Also edit and publish other users’ posts and pages. They have unfiltered_html, so posts may contain <script> Avoid

The content the AI client writes comes partly from what it reads: a web page, a comment, or a post can contain instructions that make it write something else (prompt injection). With Editor or Administrator, such content can publish a post with <script> that runs in your visitors’ browsers at once. With Contributor, nothing is published until you do it, and WordPress removes <script> from what a Contributor or an Author saves.

  1. Go to WordPress Admin → Users → Profile
  2. Scroll to Application Passwords section
  3. Enter application name (e.g., “MCP-RS Integration”)
  4. Click Add New Application Password
  5. Copy the generated password to your config

Available Tools

Core Content Management

create_post

Create a new WordPress post (basic version).

Parameters:

  • title (string): Post title
  • content (string): Post content (HTML supported)
  • slug (string, optional): URL slug, for example an English slug for a post with a Japanese title. If omitted, WordPress generates one from the title. See Slugs

Example Usage:

{
  "tool": "create_post",
  "arguments": {
    "title": "My New Blog Post",
    "content": "<p>This is the content of my post with <strong>HTML formatting</strong>.</p>"
  }
}

create_advanced_post

Create a new WordPress post or page with advanced options.

Parameters:

  • title (string): Post/page title
  • content (string): Post/page content
  • post_type (string): “post” (投稿) or “page” (固定ページ) [default: “post”]
  • status (string, optional): “publish” (公開), “draft” (下書き), “pending” (レビュー待ち), “private” (非公開), “future” (予約投稿、dateが必須) [default: “draft”]
  • date (string, optional): Publication date (ISO8601 format, required for “future” status)
  • categories (array, optional): Category IDs (posts only)
  • tags (array, optional): Tag IDs (posts only)
  • featured_media_id (number, optional): Featured image media ID
  • meta (object, optional): Meta fields for SEO (e.g., Yoast SEO fields)
  • slug (string, optional): URL slug, for example an English slug for a post with a Japanese title. If omitted, WordPress generates one from the title. See Slugs

Example Usage:

{
  "tool": "create_advanced_post",
  "arguments": {
    "title": "SEO-Optimized Post",
    "content": "<p>Content with SEO optimization</p>",
    "post_type": "post",
    "status": "draft",
    "categories": [1, 5],
    "tags": [10, 15, 20],
    "featured_media_id": 123,
    "meta": {
      "_yoast_wpseo_metadesc": "Custom meta description",
      "_yoast_wpseo_meta-robots-noindex": "1"
    }
  }
}

create_post_with_embeds

Create a post or page with embedded YouTube videos and social media content appended to the base content.

Parameters:

  • title (string): Post title
  • content (string): Base post content (embeds are added after it)
  • youtube_urls (array of strings, optional): YouTube video URLs to embed
  • social_urls (array of strings, optional): Social media URLs to embed (Twitter, Instagram, Facebook, TikTok)
  • post_type (string, optional): post or page
  • status (string, optional): publish, draft, pending, or private. Defaults to draft. future (scheduled) is not available because this tool has no date parameter
  • categories (array of numbers, optional): Category IDs (posts only)
  • tags (array of numbers, optional): Tag IDs (posts only)
  • slug (string, optional): URL slug, for example an English slug for a post with a Japanese title. If omitted, WordPress generates one from the title. See Slugs

Example Usage:

{
  "tool": "create_post_with_embeds",
  "arguments": {
    "title": "Rust Conference Highlights",
    "content": "<p>Here are the talks we enjoyed most.</p>",
    "youtube_urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
    "status": "draft"
  }
}

update_post

Update an existing WordPress post.

Parameters:

  • post_id (number): ID of the post to update
  • title (string, optional): New post title
  • content (string, optional): New post content
  • status (string, optional): New post status
  • categories (array, optional): New category IDs
  • tags (array, optional): New tag IDs
  • featured_media_id (number, optional): New featured image ID
  • meta (object, optional): New meta fields
  • slug (string, optional): New URL slug. WordPress does not change the slug when the title changes. See Slugs

Example Usage:

{
  "tool": "update_post",
  "arguments": {
    "post_id": 123,
    "title": "Updated Title",
    "status": "publish",
    "categories": [1, 2, 3]
  }
}

delete_post

Delete a WordPress post.

Parameters:

  • post_id (number): ID of the post to delete
  • force (boolean, optional): Permanently delete (true) or move to trash (false) [default: false]

Slugs

The post creation tools and update_post accept an optional slug. Without it, WordPress generates the slug from the title, so a Japanese title gives a Japanese slug (percent-encoded in the URL). To use an English slug, pass it when creating the post:

{
  "tool": "create_post",
  "arguments": {
    "title": "はじめての投稿",
    "content": "<p>本文</p>",
    "slug": "my-first-post"
  }
}

Or change the slug of an existing post or page. Only the slug is changed:

{
  "tool": "update_post",
  "arguments": {
    "post_id": 123,
    "slug": "my-first-post"
  }
}

Notes:

  • WordPress may change the slug you pass. It removes characters that cannot be used in a URL, and appends -2 and so on if another post already uses the slug. The tool result shows the actual slug, for example Slug: my-first-post-2
  • For a draft, WordPress keeps the slug as given and makes it unique when the post is published
  • Changing the slug of a published post changes its URL. Whether the old URL redirects depends on WordPress and your plugins; mcp-rs does not set up redirects
  • An empty slug is rejected. Omit slug to leave it unchanged

Content Retrieval

get_posts

Retrieve WordPress posts.

get_pages

Retrieve WordPress pages.

get_all_content

Retrieve both WordPress posts and pages.

get_post

Retrieve a single WordPress post or page by ID, with its full content (not truncated).

Parameters:

  • post_id (number): ID of the post or page to retrieve
  • post_type (string, optional): post (default) or page
  • format (string, optional): How to return the title and content
    • raw (default): The editable source, including Gutenberg block markup. It can be passed back to update_post unchanged. Requires credentials with edit permission. Without it, the rendered HTML is returned instead, and the Format: line says so
    • rendered: The HTML as displayed on the site
    • text: Plain text with tags removed

For a password-protected post read without edit permission, WordPress hides the content, and the output includes a note not to treat the content as empty.

The output has a Slug: line with the post’s URL slug (a Japanese slug is shown decoded). A draft created without a slug shows none, because WordPress generates the slug when the post is published.

The output also has a Featured Media: line with the featured image’s media ID and URL, for example Featured Media: 123 (https://example.com/wp-content/uploads/photo.png). It shows none when no featured image is set. If the media item cannot be fetched, only the ID is shown.

Media Management

upload_media

Upload a media file to WordPress media library.

Parameters: Pass either file_data or file_path, not both.

  • file_data (string): Base64-encoded file data
  • file_path (string): Absolute path of a file on the machine running mcp-rs. Disabled unless upload_allowed_dirs is set
  • filename (string): Original filename. Its extension must match mime_type (e.g., photo.jpg for image/jpeg). Required with file_data. With file_path, defaults to the file’s name
  • mime_type (string): MIME type. Must be one of the supported file types. Required with file_data. With file_path, defaults to the type for the file’s extension

The upload is rejected before anything is sent to WordPress if the MIME type is not supported, the extension does not match the MIME type, the file content does not match the MIME type, the filename contains path separators or control characters, or the file is too large. These checks apply to file_path too, so files other than the supported types (such as .env) cannot be sent even from an allowed folder.

file_path restrictions:

  • The path must be absolute
  • The file must be inside one of the upload_allowed_dirs folders. The check uses the resolved path, so .. and symbolic links (or junctions on Windows) cannot point outside them
  • A path outside the allowed folders and a file that does not exist give the same error, so the error does not reveal which files exist elsewhere
  • With STDIO (Claude Code, Claude Desktop), mcp-rs runs on the same machine as the client, so it reads the client’s local files. Over HTTP/WebSocket, the client may be on another machine, and the files are read from the server. mcp-rs logs a warning at startup in that case
  • The uploaded file is public at once: WordPress gives every media file a URL that anyone can open (the source_url in the result), even before it is used in a post. Put only files you are willing to publish in upload_allowed_dirs

Example Usage:

{
  "tool": "upload_media",
  "arguments": {
    "file_data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "filename": "hero-image.jpg",
    "mime_type": "image/jpeg"
  }
}

With file_path (filename and mime_type are taken from the file):

{
  "tool": "upload_media",
  "arguments": {
    "file_path": "C:/Users/me/Pictures/blog/hero-image.png"
  }
}

get_media

Retrieve all WordPress media files.

Parameters: None

get_media_item

Retrieve a single WordPress media item by ID.

Parameters:

  • media_id (number): Media ID to retrieve

update_media

Update WordPress media metadata (title, alt text, caption, description).

Parameters:

  • media_id (number): Media ID to update
  • title (string, optional): Media title
  • alt_text (string, optional): Alternative text for accessibility
  • caption (string, optional): Media caption
  • description (string, optional): Media description
  • post (number, optional): Post ID to attach media to

Example Usage:

{
  "tool": "update_media",
  "arguments": {
    "media_id": 123,
    "alt_text": "Product image showing red handbag",
    "caption": "Spring 2024 collection",
    "description": "Detailed view of our latest handbag design"
  }
}

delete_media

Delete WordPress media file.

Parameters:

  • media_id (number): Media ID to delete
  • force (boolean, optional): Permanently delete (bypass trash) [default: false]

WordPress does not support moving media to the trash unless the site enables it (MEDIA_TRASH), so force: true is usually required. Without it, WordPress returns rest_trash_not_supported.

create_post_with_featured_image

Create a post with a featured image in one operation.

Parameters:

  • title (string): Post title
  • content (string): Post content
  • featured_media_id (number): Media ID from uploaded image
  • status (string, optional): publish, draft, pending, or private. Defaults to draft. future (scheduled) is not available because this tool has no date parameter
  • slug (string, optional): URL slug, for example an English slug for a post with a Japanese title. If omitted, WordPress generates one from the title. See Slugs

Set featured image for an existing post.

Parameters:

  • post_id (number): ID of the post to update
  • media_id (number): ID of the media to set as featured image

Category & Tag Management

Returns: Array of post objects with metadata

get_post

Retrieve a single WordPress post or page by ID, with its full content. See get_post above for the post_type and format parameters.

Parameters:

  • post_id (number): ID of the post or page to retrieve
  • post_type (string, optional): post (default) or page
  • format (string, optional): raw (default), rendered, or text

Example Usage:

{
  "tool": "get_post",
  "arguments": {
    "post_id": 123,
    "format": "raw"
  }
}

update_post

Update an existing WordPress post with comprehensive options.

Parameters:

  • post_id (number): ID of post to update
  • title (string, optional): New post title
  • content (string, optional): New post content
  • status (string, optional): publish, draft, pending, or private. Defaults to draft
  • categories (array, optional): Array of category IDs
  • tags (array, optional): Array of tag IDs
  • featured_media_id (number, optional): Featured image media ID
  • slug (string, optional): New URL slug. WordPress does not change the slug when the title changes. See Slugs

Example Usage:

{
  "tool": "update_post",
  "arguments": {
    "post_id": 123,
    "title": "Updated Post Title",
    "content": "<p>Updated content here...</p>",
    "status": "publish",
    "categories": [5, 12],
    "tags": [23, 45]
  }
}

delete_post

Delete a WordPress post.

Parameters:

  • post_id (number): ID of post to delete
  • force (boolean, optional): Force delete (permanently delete, bypass trash)

Example Usage:

{
  "tool": "delete_post",
  "arguments": {
    "post_id": 123,
    "force": false
  }
}

Note: When force is false (default), the post is moved to trash. When true, it’s permanently deleted.

get_comments

Retrieve WordPress comments.

Parameters:

  • post_id (number, optional): Filter comments by specific post

Example Usage:

{
  "tool": "get_comments",
  "arguments": {
    "post_id": 123
  }
}

get_categories

Retrieve all WordPress categories.

Parameters: None

Returns: Array of category objects with metadata

create_category

Create a new WordPress category.

Parameters:

  • name (string): Category name
  • description (string, optional): Category description
  • parent (number, optional): Parent category ID for hierarchical structure

Example Usage:

{
  "tool": "create_category",
  "arguments": {
    "name": "Technology",
    "description": "Posts about technology and software",
    "parent": 5
  }
}

update_category

Update an existing WordPress category.

Parameters:

  • category_id (number): ID of category to update
  • name (string, optional): New category name
  • description (string, optional): New category description

Example Usage:

{
  "tool": "update_category",
  "arguments": {
    "category_id": 10,
    "name": "Web Development",
    "description": "Updated description"
  }
}

delete_category

Delete a WordPress category.

Parameters:

  • category_id (number): ID of category to delete
  • force (boolean, optional): Force delete (bypass trash)

Example Usage:

{
  "tool": "delete_category",
  "arguments": {
    "category_id": 10,
    "force": true
  }
}

get_tags

Retrieve all WordPress tags.

Parameters: None

Returns: Array of tag objects with metadata

create_tag

Create a new WordPress tag.

Parameters:

  • name (string): Tag name
  • description (string, optional): Tag description

Example Usage:

{
  "tool": "create_tag",
  "arguments": {
    "name": "rust",
    "description": "Posts about Rust programming language"
  }
}

update_tag

Update an existing WordPress tag.

Parameters:

  • tag_id (number): ID of tag to update
  • name (string, optional): New tag name
  • description (string, optional): New tag description

Example Usage:

{
  "tool": "update_tag",
  "arguments": {
    "tag_id": 15,
    "name": "programming",
    "description": "Updated tag description"
  }
}

delete_tag

Delete a WordPress tag.

Parameters:

  • tag_id (number): ID of tag to delete
  • force (boolean, optional): Force delete (bypass trash)

Example Usage:

{
  "tool": "delete_tag",
  "arguments": {
    "tag_id": 15,
    "force": true
  }
}

create_post_with_categories_tags

Create a new WordPress post with categories and tags.

Parameters:

  • title (string): Post title
  • content (string): Post content
  • categories (array, optional): Array of category IDs
  • tags (array, optional): Array of tag IDs
  • featured_media_id (number, optional): Featured image media ID
  • slug (string, optional): URL slug, for example an English slug for a post with a Japanese title. If omitted, WordPress generates one from the title. See Slugs

Example Usage:

{
  "tool": "create_post_with_categories_tags",
  "arguments": {
    "title": "Complete Guide to Rust",
    "content": "<p>This comprehensive guide covers Rust programming...</p>",
    "categories": [5, 12],
    "tags": [23, 45, 67],
    "featured_media_id": 89
  }
}

update_post_categories_tags

Update categories and tags for an existing WordPress post.

Parameters:

  • post_id (number): ID of post to update
  • categories (array, optional): Array of category IDs to set
  • tags (array, optional): Array of tag IDs to set

Example Usage:

{
  "tool": "update_post_categories_tags",
  "arguments": {
    "post_id": 123,
    "categories": [5, 8],
    "tags": [15, 20, 25]
  }
}

Site Settings

get_settings

Retrieve the WordPress site settings (title, tagline, timezone, front page configuration, posts per page, default category, language, and so on).

Parameters: None

update_settings

Update WordPress site settings. Only the specified fields are changed.

Parameters (all optional):

  • title (string): Site title
  • description (string): Site tagline
  • timezone (string): Site timezone (e.g., Asia/Tokyo)
  • show_on_front (string): posts or page
  • page_on_front (number): Static front page ID (when show_on_front is page)
  • page_for_posts (number): Posts page ID (when show_on_front is page)
  • posts_per_page (number): Number of posts per page
  • default_category (number): Default category for new posts
  • language (string): Site language code (e.g., ja, en_US)

Example Usage:

{
  "tool": "update_settings",
  "arguments": {
    "description": "Notes on Rust and AI agents",
    "timezone": "Asia/Tokyo"
  }
}

set_front_page

Set a static page as the front page.

Parameters:

  • page_id (number): ID of the page to show on the front page

set_front_page_to_posts

Set the front page to show the latest posts.

Parameters:

  • posts_page_id (number, optional): ID of a page to use for the blog posts

Workflow Examples

Basic Blog Post


AI automatically:
1. Uses create_post tool
2. Generates title and content
3. Returns post URL and ID


AI automatically:
1. Uses upload_media with base64 image data
2. Uses create_post_with_featured_image with returned media ID
3. Creates complete post with featured image

Update Existing Post


AI automatically:
1. Uploads image using upload_media
2. Uses set_featured_image to update post
3. Confirms successful update

Category Management Workflow


AI automatically:
1. Uses create_category with name and description
2. Returns category ID and details
3. Can be used for organizing posts

User: "Create a subcategory under Technology"
AI automatically:
1. Uses get_categories to find Technology category ID
2. Uses create_category with parent parameter
3. Creates hierarchical category structure

Tag Management Workflow


AI automatically:
1. Uses create_tag for each relevant tag (rust, programming, tutorial)
2. Returns tag IDs for future reference
3. Tags can be applied to posts during creation

User: "Update the description of the 'rust' tag"
AI automatically:
1. Uses get_tags to find tag ID
2. Uses update_tag with new description
3. Confirms update success

Smart Content Creation Workflow


AI intelligently:
1. Uses get_categories to find existing categories
2. Finds "Technology" category (avoids creating duplicates)
3. Suggests relevant tags from get_tags
4. Uses create_post_with_categories_tags with proper taxonomy
5. Creates well-organized content

User: "Add the 'tutorial' tag to post #456"
AI automatically:
1. Gets current post categories/tags using get_posts
2. Adds new tag to existing taxonomy
3. Uses update_post_categories_tags to preserve existing data
4. Confirms successful update

Complete Content Management Workflow


AI automatically:
1. Uses get_post to retrieve current post details
2. Shows current title, content, and taxonomy
3. Uses update_post with new title and categories
4. Preserves existing content and other metadata
5. Confirms successful update

User: "Delete the draft post about outdated technology"
AI automatically:
1. Uses get_posts to find draft posts
2. Identifies the specific post by content analysis
3. Uses delete_post with force=false (moves to trash)
4. Confirms post moved to trash for recovery if needed

Content Lifecycle Management


AI automatically:
1. Uses get_post to retrieve draft details
2. Uses upload_media for featured image
3. Uses update_post with status="publish" and featured_media_id
4. Complete publication workflow in one operation

User: "Archive old posts from 2022"
AI automatically:
1. Uses get_posts to find posts from 2022
2. Shows list for user confirmation
3. Uses update_post to change status to "private"
4. Bulk content management operation

AI-Assisted Taxonomy Management


AI intelligently:
1. Uses get_categories to scan existing categories
2. Finds similar: "Web Development", "ウェブ技術", "webdev"
3. Suggests: "Should I use existing 'Web Development' or create new 'ウェブ開発'?"
4. User confirms choice
5. Creates post with appropriate categorization

This workflow prevents duplicate/similar categories and maintains clean taxonomy structure.

Error Handling

The WordPress integration includes comprehensive error handling:

  • Authentication Errors: Invalid credentials or permissions
  • API Errors: WordPress REST API specific errors
  • Network Errors: Timeout, connection failures
  • Validation Errors: Invalid parameters or data format
  • File Upload Errors: Unsupported file types or size limits

All errors include detailed messages for debugging and user feedback.

Supported File Types

upload_media accepts only the following types. Each file’s content is checked against its type’s magic number.

Type MIME type Extensions
JPEG image/jpeg .jpg, .jpeg, .jpe
PNG image/png .png
GIF image/gif .gif
WebP image/webp .webp
PDF application/pdf .pdf
MP4 video video/mp4 .mp4, .m4v
WebM video video/webm .webm
Ogg video video/ogg .ogv
MP3 audio audio/mpeg .mp3
MP4 audio audio/mp4 .m4a
WAV audio audio/wav .wav
Ogg audio audio/ogg .ogg, .oga

MIME types are case-insensitive, parameters such as ; charset=... are ignored, and common aliases (image/jpg, image/pjpeg, image/x-png, audio/mp3, audio/x-m4a, audio/x-wav) are accepted.

The following are intentionally not supported:

  • SVG: can embed scripts. WordPress also disables it by default
  • Plain text: has no magic number, so its content cannot be checked
  • Office documents (.doc, .docx, etc.): the content can only be identified as a ZIP archive
  • QuickTime (.mov): the order of its leading data is not fixed, so it cannot be identified reliably

Size limits: files larger than 10 MiB are rejected. With file_data, the transport’s message size limit (1 MiB by default for STDIO and HTTP, including the roughly 33% base64 overhead) usually applies first. file_path is not affected by that limit. WordPress’s own limits (upload_max_filesize and post_max_size) also apply.

Performance Optimization

  • Connection Pooling: Reuses HTTP connections for better performance
  • Timeout Configuration: Configurable request timeouts
  • Retry Logic: Automatic retry for transient failures (up to 3 attempts). Create and delete requests are not resent after a timeout or server error, since WordPress may already have processed them
  • Efficient Uploads: Streaming multipart uploads for large files

Troubleshooting

Common Issues

Authentication Failed

  • Verify application password is correct
  • Check username matches WordPress user
  • Ensure user has appropriate permissions

Upload Failed

  • Check file size against WordPress limits
  • Verify MIME type is supported
  • Ensure proper base64 encoding

Connection Timeout

  • Increase timeout_seconds in configuration
  • Check network connectivity
  • Verify WordPress URL is accessible

Debug Mode

Enable detailed logging by setting environment variable:


This will show detailed HTTP requests and responses for troubleshooting.


Health Check System

The WordPress MCP integration includes a comprehensive health check system to validate your environment before performing operations. This ensures reliable operation and helps identify configuration issues early.

wordpress_health_check

Perform comprehensive environment validation.

Parameters: None

Usage Example:

{
  "tool": "wordpress_health_check",
  "arguments": {}
}

Check Process

The health check performs five critical validation stages:

1. 🌐 Site Accessibility

  • Purpose: Verify WordPress site is reachable
  • Test: HTTP GET request to site URL
  • Success: Site responds with 200 OK status
  • Failure: Network timeout, DNS resolution, or server errors

2. 🔌 REST API Availability

  • Purpose: Confirm WordPress REST API is enabled and accessible
  • Test: GET request to /wp-json/wp/v2/ endpoint
  • Success: API responds with namespace information
  • Failure: REST API disabled, blocked, or misconfigured

3. 🔐 Authentication Validation

  • Purpose: Verify credentials are correct and user exists
  • Test: Authenticated request to /wp-json/wp/v2/users/me
  • Success: Returns user profile information
  • Failure: Invalid username, incorrect password, or user not found

4. ✅ Permission Verification

  • Purpose: Check user has required capabilities
  • Test: Validate publish_posts, upload_files, and edit_posts permissions
  • Success: User has all required capabilities
  • Failure: Insufficient permissions for content operations

5. 📁 Media Upload Capability

  • Purpose: Test file upload functionality end-to-end
  • Test: Upload small test image to media library
  • Success: File uploaded successfully and media ID returned
  • Failure: Upload restrictions, storage issues, or API limitations

Health Report

The health check returns a comprehensive report with the following information:

{
  "status": "healthy",
  "site_info": {
    "url": "https://your-site.com",
    "name": "Your Site Name",
    "version": "6.3.2",
    "api_version": "2.0"
  },
  "user_info": {
    "id": 1,
    "username": "admin",
    "display_name": "Site Administrator",
    "email": "admin@yoursite.com",
    "roles": ["administrator"]
  },
  "capabilities": {
    "publish_posts": true,
    "upload_files": true,
    "edit_posts": true,
    "manage_options": true
  },
  "media_upload": {
    "supported": true,
    "test_upload_id": 789,
    "max_upload_size": "64M"
  },
  "performance": {
    "response_time_ms": 245,
    "api_response_time_ms": 89
  }
}

Status Levels

🟢 Healthy

  • All checks passed
  • System ready for full operation
  • No configuration issues detected

🟡 Warning

  • Minor issues detected
  • Basic functionality available
  • Some features may be limited

🔴 Critical

  • Major issues prevent operation
  • Configuration required
  • System not usable

Troubleshooting Guide

Site Accessibility Issues


🔧 Solutions:
   • Verify URL is correct and includes https://
   • Check site is online and responding
   • Ensure firewall/security plugins allow access
   • Test URL in browser manually

REST API Problems


🔧 Solutions:
   • Enable REST API in WordPress settings
   • Check security plugins aren't blocking API
   • Verify .htaccess isn't blocking /wp-json/
   • Test API endpoint in browser: /wp-json/wp/v2/

Authentication Failures


🔧 Solutions:
   • Regenerate application password
   • Verify username is exact match
   • Check user account is active
   • Ensure application passwords are enabled

Permission Issues


🔧 Solutions:
   • Use a role that allows what you need: Contributor for drafts,
     Author to publish and upload media (avoid Editor and Administrator,
     see "Setting up Application Passwords")
   • Check user has publish_posts capability
   • Verify upload_files permission enabled
   • Review role-based access restrictions

Upload Problems


🔧 Solutions:
   • Check upload_max_filesize in php.ini
   • Verify post_max_size setting
   • Ensure uploads directory is writable
   • Check disk space availability

Best Practices

Before Production Use

  1. Run Health Check: Always validate environment first
  2. Monitor Performance: Check response times regularly
  3. Test Permissions: Verify all required capabilities
  4. Validate Uploads: Confirm media functionality works

Production Operations

Application Password Management

WordPress application passwords may be invalidated by:

  • Hosting Provider Policies: Automatic expiration by hosting services
  • Security Plugin Policies: Plugins like SiteGuard enforcing rotation
  • WordPress Updates: Major core updates affecting authentication
  • Server Changes: PHP or environment configuration modifications

Monitoring Strategy:


## Daily health monitoring (recommended)

cargo run --example comprehensive_test

## Deep diagnostic for authentication issues

cargo run --example settings_api_deep_diagnosis

## Authentication verification

cargo run --example auth_diagnosis

Maintenance Mode Operations

LightStart Plugin Configuration: When using WordPress maintenance mode plugins, configure exclusions for REST API access:


## Add to LightStart exclusions (slug format, no leading slash):

wp-json/*

This ensures MCP-RS can continue content operations during maintenance windows.

Benefits:

  • ✅ Content management continuity during maintenance
  • ✅ Zero-downtime WordPress updates
  • ✅ Emergency content access during site maintenance

Production Monitoring

Alert Criteria:

  • HTTP 401 Errors: Application password expiration → Regenerate password
  • Connection Timeouts: Network/hosting issues → Check infrastructure
  • API Changes: Plugin/core updates → Verify endpoint compatibility
  • SSL Issues: Certificate problems → Update certificates

Incident Response:

  1. Detection: Automated monitoring or error reports
  2. Diagnosis: Run settings_api_deep_diagnosis for detailed analysis
  3. Classification:
    • Password issue → WordPress Admin → Generate new application password
    • Plugin interference → Configure maintenance mode exclusions
    • Network problems → Infrastructure team investigation
  4. Resolution: Apply fix and verify with comprehensive test
  5. Documentation: Update operational logs and procedures

Automated Monitoring


use mcp_rs::handlers::wordpress::WordPressHandler;

async fn monitor_wordpress_health() {
    let handler = WordPressHandler::new(config).await?;

    match handler.health_check().await {
        Ok(report) if report.status == "healthy" => {
            println!("✅ WordPress system healthy");
        },
        Ok(report) => {
            println!("⚠️ Issues detected: {}", report.status);
            // Handle warnings or critical issues
        },
        Err(e) => {
            println!("❌ Health check failed: {}", e);
            // Alert administrators
        }
    }
}

Integration Workflow


   ├── Configure mcp-config.toml
   ├── Run wordpress_health_check
   └── Address any issues found

2. Validation Success
   ├── Proceed with content operations
   ├── Monitor performance metrics
   └── Schedule regular health checks

3. Issue Detection
   ├── Review detailed error messages
   ├── Apply recommended solutions
   └── Re-run health check to verify fixes

4. Production Monitoring
   ├── Weekly comprehensive tests
   ├── Application password rotation (as needed)
   ├── Maintenance mode coordination
   └── Incident response procedures

This health check system ensures your WordPress integration is production-ready and helps prevent common configuration issues that could interrupt your workflow.