AI & MCP Integration

Experimental Feature

This feature is experimental and currently available only for site administrators. The WordPress Abilities API and MCP ecosystem are still evolving, and the API may change in future versions.

Better Messages registers WordPress Abilities that allow AI tools to interact with your messaging system. AI assistants can send messages, read conversations, search users, manage participants, and more.

Requirements

WordPress 6.9 or higher (Abilities API is included in WordPress core)
Better Messages 2.14.11 or higher
For MCP connections: WordPress MCP Adapter plugin

Available Abilities

Messages

Ability	Description	Parameters
`better-messages/send-message`	Send a message to a conversation	`thread_id`, `message`, `sender_id` (optional)
`better-messages/get-messages`	Read messages from a conversation	`thread_id`, `count` (optional)
`better-messages/search-messages`	Search messages by keyword (returns matching content)	`query`
`better-messages/edit-message`	Edit an existing message	`thread_id`, `message_id`, `message`
`better-messages/delete-messages`	Delete messages	`thread_id`, `message_ids`

Conversations

Ability	Description	Parameters
`better-messages/list-conversations`	List conversations for a user	`user_id` (optional), `exclude` (optional)
`better-messages/get-conversation`	Get conversation with messages	`thread_id`, `messages_count` (optional)
`better-messages/create-conversation`	Start a new conversation	`recipients`, `message`, `subject` (optional)
`better-messages/get-private-conversation`	Get or create a 1-on-1 conversation	`user_id`, `create` (optional)
`better-messages/delete-conversation`	Delete a conversation	`thread_id`
`better-messages/mark-read`	Mark conversations as read	`thread_ids` (optional, empty = mark all)
`better-messages/change-subject`	Change conversation subject	`thread_id`, `subject`
`better-messages/get-stats`	Get messaging statistics	—

Participants

Ability	Description	Parameters
`better-messages/list-participants`	List conversation participants	`thread_id`
`better-messages/add-participant`	Add users to a conversation	`thread_id`, `user_ids`
`better-messages/remove-participant`	Remove a user from a conversation	`thread_id`, `user_id`
`better-messages/make-moderator`	Grant moderator role	`thread_id`, `user_id`
`better-messages/unmake-moderator`	Remove moderator role	`thread_id`, `user_id`

Users

Ability	Description	Parameters
`better-messages/search-users`	Search users by name	`query`, `limit` (optional)
`better-messages/get-unread-count`	Get unread message count	`user_id` (optional)

Moderation

Ability	Description	Parameters
`better-messages/get-pending-messages`	View moderation queue	`page` (optional), `per_page` (optional)
`better-messages/approve-message`	Approve a pending message	`message_id`
`better-messages/reject-message`	Reject and delete a pending message	`message_id`
`better-messages/blacklist-user`	Add user to blacklist	`user_id`
`better-messages/unblacklist-user`	Remove user from blacklist	`user_id`
`better-messages/whitelist-user`	Add user to whitelist	`user_id`
`better-messages/unwhitelist-user`	Remove user from whitelist	`user_id`

Connecting AI Tools

Option 1: Local WordPress (Claude Desktop, Cursor, VS Code)

This method works when your AI tool runs on the same machine as WordPress (local development).

Step 1. Install and activate the WordPress MCP Adapter plugin.

Step 2. Add the following to your AI tool's MCP configuration:

Claude Desktop — Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress",
        "mcp-adapter", "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}

Cursor — Go to Settings → Tools and MCP → Add Custom MCP, use the same format.

VS Code — Create .vscode/mcp.json in your project:

{
  "servers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress",
        "mcp-adapter", "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}

Replace /path/to/your/wordpress with the actual path to your WordPress installation and admin with your WordPress username.

Option 2: Remote WordPress (hosted sites)

This method works with any hosted WordPress site accessible over HTTPS. Requires Node.js installed on your computer.

Step 1. Install and activate the WordPress MCP Adapter plugin.

Step 2. Create an Application Password in WordPress: go to Users → Profile → Application Passwords, enter a name (e.g. "Claude Desktop"), and click Add New Application Password. Copy the generated password.

Step 3. Add the following to your AI tool's MCP configuration:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://yoursite.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Replace yoursite.com with your domain, and fill in your username and application password.

Option 3: REST API (no MCP needed)

You can use Better Messages abilities directly through the WordPress REST API without any additional plugins.

List available abilities:

GET https://yoursite.com/wp-json/wp-abilities/v1/abilities?category=better-messages

Execute an ability:

POST https://yoursite.com/wp-json/wp-abilities/v1/abilities/better-messages/send-message/run
Content-Type: application/json
Authorization: Basic {base64(username:app_password)}

{
  "input": {
    "thread_id": 123,
    "message": "Hello from the API!"
  }
}

Usage Examples

Once connected, you can ask your AI assistant things like:

"Show me the messaging statistics"
"List conversations for user 42"
"Send a message to conversation 123 saying hello"
"Search for messages containing 'invoice'"
"Create a new conversation with user 5 saying welcome"
"Show me the moderation queue"
"Approve all safe pending messages"
"Blacklist user 7"
"Make user 10 a moderator in conversation 200"

Permissions

All abilities require WordPress administrator access (manage_options capability). The authenticated administrator has full access to all conversations and messages across the site.

Troubleshooting

Abilities not showing up in MCP? Make sure the WordPress MCP Adapter plugin is installed and activated. Better Messages abilities are registered with mcp.public = true and should appear automatically.

Authentication errors? For remote connections, make sure your site uses HTTPS (required for Application Passwords) and that the application password is entered correctly with spaces between each group.

"Ability not found" errors? Make sure Better Messages is activated and you are running WordPress 6.9 or higher. You can verify abilities are registered by visiting:

https://yoursite.com/wp-json/wp-abilities/v1/abilities

Feedback & Missing Features

This feature is under active development. If you need an ability that is not listed here or have suggestions for improvement, please contact us at support@better-messages.com — we would love to hear your feedback.

Available Abilities​

Messages​

Conversations​

Participants​

Users​

Moderation​

Connecting AI Tools​

Option 1: Local WordPress (Claude Desktop, Cursor, VS Code)​

Option 2: Remote WordPress (hosted sites)​

Option 3: REST API (no MCP needed)​

Usage Examples​

Permissions​

Troubleshooting​

Feedback & Missing Features​