wp_delete_post: delete a post
Trashes a post, or removes it permanently. The only tool in this chapter marked destructive.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The post to delete |
force |
No | Permanently delete instead of trashing |
dry_run |
No | Report without deleting |
Permissions
Allow content writes open, and delete_post on that specific item — a different capability from edit_post, so a user who can edit a post cannot necessarily delete it.
Scopes: mcp:read, mcp:write, wp:content:read, wp:content:write.
Trash versus force
Without force the post goes to the WordPress trash. It disappears from the site and remains recoverable from Posts → Trash until the trash is emptied.
With force it is removed permanently. There is no trash, no revision and no recovery short of a database backup.
The difference is the whole safety story of this tool. Default to trashing, and treat force as an operation that needs a reason.
Trash post 412. Do not use force.
Always dry run first
dry_run returns would_delete with the record, which confirms you are about to delete what you think you are.
Use a dry run and show me the post you would delete.
For a deletion, that confirmation is worth the extra call every time. A well-formed delete of the wrong ID is indistinguishable from a correct one until someone notices the missing page.
What it returns
deleted and the id. Not the record — read it before deleting if you want it recorded.
Before deleting anything
- Confirm the identity. Read the post and check the title.
- Check what links to it. A deleted page leaves broken internal links and dead menu items.
- Check whether it is in a menu. See Site and menu tools.
- Consider whether unpublishing is enough. Setting a post to draft removes it from the site and keeps everything.
That last point is the one worth reaching for. "Take this off the site" is almost always satisfied by a status change rather than a deletion.
Deleting several
Never delegate a criterion for deletion. Name the IDs:
Trash posts 412, 415 and 418. Nothing else.
Not:
Trash the old posts.
The second delegates a judgement about your content that the assistant cannot make, and the result is not reversible without a backup if force was used.
After deleting
- Check the site for broken links to the deleted item.
- Check menus.
- Purge the cache — a cached copy of a deleted page can still be served.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_post_not_found |
Wrong ID |
pom_ai_mcp_forbidden |
No delete_post on that item |
| The post is gone permanently | force was passed |
| Broken links appeared | Content elsewhere referenced it |
| The page still loads | Cached |
Related
wp_update_post— unpublishing is usually the better answerwp_delete_page- Recover from a failed write