WordPress MCP Server

wp-mcp

@rnaga/wp-mcp is a Model Context Protocol (MCP) server for WordPress that turns your site into an AI-operable surface. By exposing WordPress CRUD primitives to clients like Claude Desktop, an assistant can draft a post on demand, refine it collaboratively, and publish it straight into your database—no trip through wp-admin required.

Here are a few common scenarios this unlocks:

• Draft, revise, and publish posts directly from MCP clients such as Claude Desktop.
• Inspect WordPress users, their roles, and capabilities to audit site permissions or generate access reports.

Built on top of @rnaga/wp-node, the server ships with a curated MCP toolset covering posts, users, comments, terms, revisions, metadata, options, and site settings. The MCP server can manage the following database tables/resources:

You can spin up a STDIO server for direct database access or host a Streamable HTTP MCP server for remote access. For convenience, layer on the CLI proxy whenever your MCP client needs a local bridge to the HTTP server. The proxy behaves like a local MCP server while relaying requests to the HTTP endpoint—perfect for clients that lack OAuth or WordPress Application Password support—so you can fit MCP workflows into existing editorial pipelines without re-implementing WordPress business logic.

The project includes a CLI (wp-mcp) that helps you:

• configure and launch a local STDIO MCP server that connects straight to your WordPress database;
• scaffold and initialize an Express-based Streamable HTTP MCP server (with env/TS boilerplate);
• authenticate against a remote WordPress environment (OAuth or Application Password) and run a JSON-RPC proxy so MCP clients can reach it securely;
• inspect available MCP primitives and manage the credentials stored under ~/.wp-mcp.

Run this command to list the available CLI commands:

npx @rnaga/wp-mcp -- --help

Usage: <command> <subcommand> [options]

Commands: local Local MCP (stdio) server commands utils Utility commands for configuration, debugging, and MCP inspection http Scaffold a TypeScript project for the MCP streamable HTTP server and related tooling. remote Remote MCP server commands

Together, the server, CLI utilities, and proxy tooling let you CRUD WordPress content, manage users, and sync settings through the MCP standard without re-implementing WordPress logic.

Getting Started

Local STDIO server

Run the STDIO server when you can reach the database directly. The CLI launches an MCP process that assumes a WordPress user locally and exposes your site's tools over STDIO to the MCP client.

flowchart LR

client(["MCP Client (e.g. Claude Desktop)"]) stdio(["Local STDIO MCP Server (wp-mcp CLI)"]) db(["WordPress Database"])

client <--> stdio stdio <--> db

1. Run the CLI to set up the database connection:

   npx @rnaga/wp-mcp -- local config-set

The CLI prompts you for host, port, database name, user, and password. If your database requires SSL, you can provide CA, cert, and key file paths to secure remote access. Run npx @rnaga/wp-mcp local config anytime to review the saved values.

1. Configure your MCP client to launch the server. For Claude Desktop, open Settings → Developer → Edit Config and add this to your claude_desktop_config.json:

   {

"mcpServers": { "wp-mcp": { "command": "npx", "args": ["-y", "@rnaga/wp-mcp", "--", "local", "start"], "env": { "LOCAL_USERNAME": "wp-admin" } } } }

Activate the server: Save the config file, then quit and restart your MCP client (for example, Claude Desktop). The WordPress tools will now appear in the MCP indicator at the bottom right of the chat input.

Important: Replace wp-admin with your WordPress username. The server uses this to determine which MCP primitives are available based on the user's WordPress capabilities. For example, administrator roles get full access to all primitives (create, update, delete posts, manage users, etc.), while subscriber roles see only limited tools. This capability-based filtering prevents accidental execution of privileged operations. To see which primitives are available and the required capabilities and roles for each:

   npx @rnaga/wp-mcp -- utils list-prims

This displays a table showing the primitive name, title, description, required capabilities, and allowed roles.

Optional: Provide a WordPress config manifest if your project defines one (e.g., src/_wp/config/wp.json). Set LOCAL_CONFIG in the env object above to the absolute path of your config file. If you don't have a custom config, omit this environment variable entirely. For the configuration manifest schema, see https://rnaga.github.io/wp-node/docs/getting-started/configuration.

Testing the MCP server:

Use the MCP Inspector for interactive testing and debugging:

   npx -y @modelcontextprotocol/inspector npx @rnaga/wp-mcp local start -u wp-admin

This opens a visual interface at http://localhost:6274 where you can explore available tools, test them with different arguments, and inspect server responses.

Note: Inspector persists its "Environment Variables" panel in browser storage across sessions. If you previously added a PATH entry there while troubleshooting, delete it manually in the UI — a stale value can shadow the environment the server actually needs and won't be overridden by CLI flags or script changes.

Usage reference for CLI flags and environment variables:

MCP Streamable HTTP server

Use the HTTP server when you need to expose MCP over the Internet or let remote teammates connect. The CLI scaffolds an Express app (see src/http/express/index.ts) that exposes both the MCP streaming HTTP transport and the SSE fallback while reusing the same primitive registry.

1. Scaffold a project

   npx @rnaga/wp-mcp -- http init

The wizard prompts for database connection details, creates a wp-node project, and seeds Express boilerplate plus TypeScript configuration for the HTTP transport.

Resulting layout:

   ├── _wp

│   ├── config │   │   ├── index.d.ts │   │   └── wp.json │   └── settings.ts ├── .env ├── .gitignore ├── index.ts ├── package-lock.json ├── package.json ├── src │   └── index.ts └── tsconfig.json

Populate .env with the values requested by the scaffolder and any HTTP-specific environment variables listed later in this document.

1. Run the server in development

   npm run dev

This relies on ts-node so you can iterate without precompiling.

1. Build and run in production

   npm run build

npm run start

The compiled output boots the same Express server that createHttpServer wires together in the library.

Connect via the Remote Proxy CLI

Use the remote proxy when your MCP client only understands STDIO or lacks full OAuth support but the WordPress environment is available over HTTP. The proxy keeps credentials in ~/.wp-mcp and relays MCP requests to the remote server with the right Authorization header.

flowchart LR

client(["MCP Client (e.g. Claude Desktop)"]) proxy(["CLI Proxy (handles OAuth or WP Application Password)"]) server(["MCP HTTP Server (Express instance in this repo)"]) db(["WordPress Database"])

client <--> proxy proxy <--> server server <--> db

1. Authenticate once

Begin by enrolling the proxy with either WordPress Application Password credentials or an OAuth device flow so it can sign requests on behalf of your MCP client.

• WordPress Application Password

sh npx @rnaga/wp-mcp -- remote login password

Provide the authorization URL for your server (for example http://localhost:3000), then enter the WordPress username and application password. The credentials are stored securely so future proxy runs can supply HTTP Basic auth automatically (WordPress Application Passwords are transmitted via the Basic scheme.)

Inspect the stored values with:

sh npx @rnaga/wp-mcp -- remote config

• OAuth device flow

sh npx @rnaga/wp-mcp -- remote login oauth

The CLI calls /auth/device/start, prints the user code, and opens the verification URL in your browser. After you complete the device flow, the access and refresh tokens are written to ~/.wp-mcp. You can re-run remote config or remote revoke-token as needed.

Use `npx @rnaga/wp-mcp -- remot