Passepartout

The master key for piloting self-hosted WordPress from any AI client.

Passepartout is a Model Context Protocol (MCP) server that lets an AI assistant — Claude Desktop today, any MCP client tomorrow — read and write content (posts, pages, media, taxonomies) across all of your self-hosted WordPress sites, using a simple shared key instead of WordPress Application Passwords.

AI client  ──MCP──►  Passepartout  ──REST + X-Passepartout-Key──►  your WordPress sites

---

Why this exists

If you run self-hosted WordPress and tried to connect it to an AI agent, you have probably hit this wall:

• Application Passwords silently disappear. Behind a reverse proxy (most managed hosts), WordPress' internal is_ssl() check fails, the "Application Passwords" section vanishes from the profile screen, and nothing tells you why.
• No OAuth for self-hosted. The official tooling assumes WordPress.com-style OAuth, which self-hosted installs don't have out of the box.
• The web connector is left out. Most self-hosted MCP paths only work with a local desktop proxy.

The lock jammed. So Passepartout is a skeleton key: a tiny companion plugin validates a secret you control (X-Passepartout-Key), and the server speaks the plain WordPress REST API. No Application Passwords, no SSL-detection roulette, and one server drives every site you own.

Named after Jules Verne's tireless globe-trotting valet — and after the French passe-partout, the key that opens every door.

---

Features

• 🔑 Custom-key auth — bypasses Application Passwords entirely.
• 🌍 Multi-site — manage many WordPress installs from a single server; target one with a site argument.
• 📝 Content tools — list/get/create/update/delete posts and pages, manage categories/tags, search, and upload media from a URL.
• 🛟 Safe by default — new posts/pages default to draft; destructive deletes are explicitly annotated and trash-first.
• 🧱 Clean TypeScript — MCP SDK, Zod-validated inputs, strict mode, MIT-licensed.

---

Quick start

1. Install the companion plugin (per site)

Copy wp-plugin/passepartout-auth.php to wp-content/mu-plugins/passepartout-auth.php on each WordPress site, then add the secret to wp-config.php (above the "That's all, stop editing!" line):

define( 'PASSEPARTOUT_KEY', 'a-long-random-secret' );
// Optional — act as a specific user instead of the first administrator:
// define( 'PASSEPARTOUT_USER_ID', 1 );

Use a long, random secret and serve the site over HTTPS.

2. Configure the server

Create a sites.json (see sites.example.json):

[
  { "id": "baair", "label": "BAAIR Solutions", "url": "https://baair.solutions", "key": "a-long-random-secret" }
]

The key here must match PASSEPARTOUT_KEY on that site.

3. Add it to your MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "passepartout": {
      "command": "npx",
      "args": ["-y", "passepartout-mcp@latest"],
      "env": {
        "PASSEPARTOUT_SITES_FILE": "/absolute/path/to/sites.json"
      }
    }
  }
}

Restart the client fully, then try: "List the draft posts on baair."

---

Configuration

Pick one of three styles:

Variable	Meaning
PASSEPARTOUT_SITES_FILE	Absolute path to a JSON array of sites (recommended).
PASSEPARTOUT_SITES	Inline JSON array of sites.
WP_URL + WP_KEY (+ WP_SITE_ID, WP_LABEL)	Single-site shorthand.

Each site object: { "id", "url", "key", "label?" }.

---

Tools

Tool	What it does	Destructive
wp_list_sites	List configured sites (never exposes keys)	no
wp_list_posts / wp_get_post	Browse and read posts	no
wp_create_post / wp_update_post	Author and edit posts (draft by default)	no
wp_delete_post	Trash (or force-delete) a post	yes
wp_list_pages / wp_get_page	Browse and read pages	no
wp_create_page / wp_update_page	Author and edit pages	no
wp_list_terms / wp_create_term	Manage categories and tags	no
wp_list_media / wp_upload_media_from_url	Browse media; import an image by URL	no
wp_search	Search posts and pages	no

---

Security model

• The companion plugin authenticates a request only when X-Passepartout-Key matches PASSEPARTOUT_KEY, using a constant-time comparison.
• The server never logs or returns your keys; wp_list_sites omits them.
• Capabilities follow the WordPress role of the resolved user — use a dedicated machine user with the least privilege you need.
• Always serve sites over HTTPS. Rotate a key by changing it on both sides.

---

Build from source

npm install
npm run build
node dist/index.js   # expects the env config above

Inspect tools interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

---

Roadmap

• Streamable HTTP transport + OAuth, for the claude.ai web connector
• Custom post types & ACF fields
• WP-CLI-over-SSH fallback adapter
• Structured (outputSchema) responses

Contributions welcome — see CONTRIBUTING.md.

License

MIT © Alexandre Bruneau (BAAIR)