WordPress Integration
WordPress Integration
Home > Documentation > WordPress Integration
Complete WordPress REST API integration with advanced media management capabilities.
Table of contents
- WordPress Integration
- Table of contents
- Overview
- Features
- 📝 Content Management
- 🖼️ Media Management
- 🔐 Security
- 🏷️ Category & Tag Management
- ⚙️ Advanced Features
- Configuration
- Setting up Application Passwords
- Available Tools
- Core Content Management
- Content Retrieval
- Media Management
- Category & Tag Management
get_postupdate_postdelete_postget_commentsget_categoriescreate_categoryupdate_categorydelete_categoryget_tagscreate_tagupdate_tagdelete_tagcreate_post_with_categories_tagsupdate_post_categories_tags- Site Settings
get_settingsupdate_settingsset_front_pageset_front_page_to_posts- Workflow Examples
- Basic Blog Post
- Featured Image Workflow
- Update Existing Post
- Category Management Workflow
- Tag Management Workflow
- Smart Content Creation Workflow
- Complete Content Management Workflow
- Content Lifecycle Management
- AI-Assisted Taxonomy Management
- Error Handling
- Supported File Types
- Performance Optimization
- Troubleshooting
- Common Issues
- Debug Mode
- Health Check System
wordpress_health_check- Check Process
- Health Report
- Status Levels
- Troubleshooting Guide
- Best Practices
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 ofusername/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 inenvof its JSON config. See Which environment variables reach mcp-rsencrypted_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.
- Go to WordPress Admin → Users → Profile
- Scroll to Application Passwords section
- Enter application name (e.g., “MCP-RS Integration”)
- Click Add New Application Password
- 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 titlecontent(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 titlecontent(string): Post/page contentpost_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 IDmeta(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 titlecontent(string): Base post content (embeds are added after it)youtube_urls(array of strings, optional): YouTube video URLs to embedsocial_urls(array of strings, optional): Social media URLs to embed (Twitter, Instagram, Facebook, TikTok)post_type(string, optional):postorpagestatus(string, optional):publish,draft,pending, orprivate. Defaults todraft.future(scheduled) is not available because this tool has no date parametercategories(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 updatetitle(string, optional): New post titlecontent(string, optional): New post contentstatus(string, optional): New post statuscategories(array, optional): New category IDstags(array, optional): New tag IDsfeatured_media_id(number, optional): New featured image IDmeta(object, optional): New meta fieldsslug(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 deleteforce(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
-2and so on if another post already uses the slug. The tool result shows the actual slug, for exampleSlug: 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
slugis rejected. Omitslugto 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 retrievepost_type(string, optional):post(default) orpageformat(string, optional): How to return the title and contentraw(default): The editable source, including Gutenberg block markup. It can be passed back toupdate_postunchanged. Requires credentials with edit permission. Without it, the rendered HTML is returned instead, and theFormat:line says sorendered: The HTML as displayed on the sitetext: 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 datafile_path(string): Absolute path of a file on the machine running mcp-rs. Disabled unlessupload_allowed_dirsis setfilename(string): Original filename. Its extension must matchmime_type(e.g.,photo.jpgforimage/jpeg). Required withfile_data. Withfile_path, defaults to the file’s namemime_type(string): MIME type. Must be one of the supported file types. Required withfile_data. Withfile_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_dirsfolders. 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_urlin the result), even before it is used in a post. Put only files you are willing to publish inupload_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 updatetitle(string, optional): Media titlealt_text(string, optional): Alternative text for accessibilitycaption(string, optional): Media captiondescription(string, optional): Media descriptionpost(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 deleteforce(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 titlecontent(string): Post contentfeatured_media_id(number): Media ID from uploaded imagestatus(string, optional):publish,draft,pending, orprivate. Defaults todraft.future(scheduled) is not available because this tool has no date parameterslug(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
Set featured image for an existing post.
Parameters:
post_id(number): ID of the post to updatemedia_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 retrievepost_type(string, optional):post(default) orpageformat(string, optional):raw(default),rendered, ortext
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 updatetitle(string, optional): New post titlecontent(string, optional): New post contentstatus(string, optional):publish,draft,pending, orprivate. Defaults todraftcategories(array, optional): Array of category IDstags(array, optional): Array of tag IDsfeatured_media_id(number, optional): Featured image media IDslug(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 deleteforce(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 namedescription(string, optional): Category descriptionparent(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 updatename(string, optional): New category namedescription(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 deleteforce(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 namedescription(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 updatename(string, optional): New tag namedescription(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 deleteforce(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 titlecontent(string): Post contentcategories(array, optional): Array of category IDstags(array, optional): Array of tag IDsfeatured_media_id(number, optional): Featured image media IDslug(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 updatecategories(array, optional): Array of category IDs to settags(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 titledescription(string): Site taglinetimezone(string): Site timezone (e.g.,Asia/Tokyo)show_on_front(string):postsorpagepage_on_front(number): Static front page ID (whenshow_on_frontispage)page_for_posts(number): Posts page ID (whenshow_on_frontispage)posts_per_page(number): Number of posts per pagedefault_category(number): Default category for new postslanguage(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
Featured Image Workflow
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 |
application/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_secondsin 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
- Run Health Check: Always validate environment first
- Monitor Performance: Check response times regularly
- Test Permissions: Verify all required capabilities
- 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:
- Detection: Automated monitoring or error reports
- Diagnosis: Run
settings_api_deep_diagnosisfor detailed analysis - Classification:
- Password issue → WordPress Admin → Generate new application password
- Plugin interference → Configure maintenance mode exclusions
- Network problems → Infrastructure team investigation
- Resolution: Apply fix and verify with comprehensive test
- 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.