DEV Community: rnaga

MCP for WordPress: Write and Publish Posts from Your AI Assistant

rnaga — Wed, 15 Oct 2025 13:16:51 +0000

I recently introduced wp-node, which mirrors WordPress core data structures and CRUD operations.

Building on that idea, I’ve now developed wp-mcp — a Model Context Protocol (MCP) server for WordPress that exposes your site’s content and settings as AI-accessible primitives. With it, tools like Claude Desktop can draft, edit, and publish posts straight into your database without touching wp-admin — and no PHP or traditional LAMP stack required, just pure MCP and TypeScript.

Imagine telling Claude Desktop:

“Draft a post called Exploring Headless WordPress and publish it when done.”

wp-mcp makes that possible — all through the MCP standard.

You can check out the full documentation and setup instructions in the project’s README.md

If you find it useful, don’t forget to ⭐️ star the repo!

What is wp-mcp?

@rnaga/wp-mcp turns your WordPress into an AI-operable surface.

It extends the TypeScript foundation of @rnaga/wp-node and ships with a rich set of MCP tools that map directly to your WordPress database — including posts, users, comments, terms, metadata, options, and settings.

Through the MCP standard, any compatible AI client (like Claude Desktop) can perform WordPress CRUD actions — safely and capability-aware — without you writing custom endpoints or plugins.

Key capabilities

Draft, revise, and publish posts directly from an MCP client
Moderate comments or auto-generate replies using AI
Inspect and manage users with proper role and capability checks
Work with taxonomies like categories, tags, and custom terms
Read or update site options and network-level settings

Why wp-mcp?

🧩 TypeScript-first — no PHP or traditional LAMP stack required
⚡ Local + Remote MCP server support (STDIO and Streamable HTTP)
🔐 Built-in Remote Proxy for clients that only support STDIO
🧠 Capability-aware — tools filter by actual WordPress roles
🛠️ Extensible — easily build custom primitives (tools, resources, prompts)

Getting Started

All setup goes through the wp-mcp CLI.

You can check available commands with:

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

A) Local STDIO Server

Use this when you can connect directly to the WordPress database.

Configure database connection

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

You’ll be prompted for host, port, database, username, and password.

Set up your MCP client (for example, Claude Desktop):

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

Replace wp-admin with your WordPress username.

Restart Claude Desktop, and you’ll see WordPress tools appear under the MCP panel.

Inspect available primitives

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

This shows which MCP tools your WordPress role can use (create posts, manage users, etc.).

B) Streamable Remote HTTP Server

Use this when you need to share access or host your MCP server remotely.

Scaffold the project

npx @rnaga/wp-mcp -- http init

This generates an Express-based TypeScript project with all boilerplate in place.

Run in development

npm run dev

Build and start in production

npm run build
npm run start

The HTTP transport supports streaming MCP and SSE fallback, with built-in OAuth and Application Password authentication.

Remote Proxy Mode

If your MCP client doesn’t fully support OAuth authentication or Streamable HTTP, you can use the proxy. It acts as a local STDIO server while securely forwarding requests to the remote HTTP endpoint.

This is especially helpful for clients like Claude Desktop, where HTTP connections are available only in the paid tier or OAuth support is limited.

1) Authenticate

WordPress Application Password:

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

OAuth Device Flow:

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

Credentials are stored securely in ~/.wp-mcp.

You can inspect them later with:

npx @rnaga/wp-mcp -- remote config

2) Start the Proxy

In your Claude Desktop config:

{
  "mcpServers": {
    "wp-mcp": {
      "command": "npx",
      "args": ["-y", "@rnaga/wp-mcp", "--", "remote", "proxy"],
      "env": {
        "REMOTE_AUTH_TYPE": "oauth",
        "REMOTE_URL": "https://wp-mcp.example.com/mcp"
      }
    }
  }
}

Now your MCP client connects locally, and the proxy securely forwards every request to the remote server.

Building Custom MCP Primitives

You can extend wp-mcp with your own MCP primitives — tools, resources, or prompts — using decorators.

1) Scaffold your project

Local (STDIO)

npx @rnaga/wp-mcp -- local init

Remote (HTTP)

npx @rnaga/wp-mcp -- http init

2) Add a primitive class

Create src/example-suite.mcp.ts:

import { z } from "zod";
import { mcp, mcpBind } from "@rnaga/wp-mcp/decorators";
import { Mcps } from "@rnaga/wp-mcp/mcp";
import type * as types from "@rnaga/wp-mcp/types";

@mcp("example_suite", {
  description: "Example bundle showing tools, resources, and prompts.",
})
export class ExampleSuiteMcp {
  @mcpBind("example_tool", {
    title: "List Options",
    description: "Return the WordPress options table as JSON.",
    capabilities: ["read"],
  })
  example(...args: types.McpBindParameters) {
    const [server, username, meta] = args;

    server.registerTool(
      meta.name,
      {
        title: meta.title,
        description: meta.description,
        inputSchema: undefined,
      },
      async () => {
        const wp = await Mcps.getWpContext(username);
        const options = await wp.utils.crud.options.getAll();

        return {
          content: [
            { type: "text", text: JSON.stringify(options, null, 2) },
          ],
        };
      }
    );

    return server;
  }
}

3) Register it in your entry point

Local STDIO:

import { createLocalServer } from "@rnaga/wp-mcp/cli/local";
import { ExampleSuiteMcp } from "./example-suite.mcp";

(async () => {
  const mcpServer = await createLocalServer({
    username: process.env.LOCAL_USERNAME,
    mcps: [ExampleSuiteMcp],
  });
})();

Remote HTTP:

import { MemoryCache } from "@rnaga/wp-mcp/http/cache/memory-cache";
import { createHttpServer } from "@rnaga/wp-mcp/http/express";
import { ExampleSuiteMcp } from "./example-suite.mcp";

const app = createHttpServer({
  cacheClass: MemoryCache,
  mcps: [ExampleSuiteMcp],
});

Restart your server, and your custom tools appear instantly in your MCP client.

In Summary

wp-mcp bridges WordPress and AI clients through the Model Context Protocol, letting you manage, create, and publish WordPress content without touching PHP or wp-admin.

✅ Works with Local STDIO and Remote Streamable HTTP servers

✅ Includes a Remote Proxy for STDIO-only clients

✅ Extensible through custom primitives

✅ Built on TypeScript — no PHP, no LAMP stack

Quick Start Recap

# Configure local STDIO server
npx @rnaga/wp-mcp -- local config-set

# Start locally
npx @rnaga/wp-mcp -- local start

# Scaffold remote HTTP server
npx @rnaga/wp-mcp -- http init

# Authenticate for remote proxy
npx @rnaga/wp-mcp -- remote login oauth
npx @rnaga/wp-mcp -- remote proxy

With wp-mcp, WordPress becomes a seamless extension of your AI assistant — ready to draft, edit, and publish at your command.

WP-Next: A Headless WordPress Admin Built with Next.js (No PHP Required)

rnaga — Tue, 26 Aug 2025 15:02:00 +0000

Tired of the classic, PHP-bound WordPress admin? WP-Next reimagines it with a modern stack. Built entirely with Next.js and WP-Node, WP-Next delivers a headless CMS experience for managing posts, pages, media, comments, users, and more—without writing any PHP.

👉 Check out the repo here: https://github.com/rnaga/wp-next — and don’t forget to leave a star if you find it useful! ⭐

Under the hood, WP-Next uses Next.js Server Functions (powered by WP-Node) to interact with your WordPress database. That means a clean, React-first workflow in TypeScript, server-side data handling, and a development process that feels just like building any modern Next.js app.

Why it stands out

Headless by design: Manage WordPress content with a React-powered admin.
Next.js + TypeScript: Familiar tools for building, extending, and customizing.
WP-Node integration: Direct access to WordPress data through Node.js.
No PHP required: Everything runs in JavaScript/TypeScript, front to back.

With WP-Next, you keep WordPress’s proven content model while gaining the speed and flexibility of a Next.js application.

Quick Demo

The fastest way to try out WP-Next is by running the prebuilt demo image with Docker.

docker run --rm --init -it --name wp-next-example -p 3000:3000 \
  -v wp-next-example_public:/app/admin/public \
  -v wp-next-example_db:/var/lib/mysql \
  -v wp-next-example_html:/app/html \
  rnagat/wp-next-example:latest

Once the container is running, open http://localhost:3000/admin in your browser and log in with:

Username: wp  
Password: wp

When you’re done, you can stop and remove the running container with:

docker stop wp-next-example

Admin Dashboard

The main feature of WP-Next is the Admin Dashboard—a headless CMS that serves as a modern alternative to the traditional WordPress Admin Dashboard.

Out of the box, it includes:

Posts & Pages – create, edit, and manage content
Media – upload and organize images, videos, and files
Terms – categories, tags, and other taxonomies
Comments – moderate and manage discussions
Profile & Settings – manage user profiles and account preferences
Users and Roles – add, edit, and assign capabilities
Revisions – track and roll back content changes

WP-Next also supports multi-site / multi-network mode, enabling you to manage multiple WordPress sites from the same admin interface:

Sites – manage and configure multiple sites in one network
Blogs – per-site content such as posts, media, and comments

Notes

Since WP-Next is fully written in TypeScript and React, certain WordPress features are not supported, including:

WordPress Themes and appearance settings
WordPress Block Editor (Gutenberg)
WordPress template rendering APIs
WordPress plugins

Core Libraries

WP-Next is built on top of a modern TypeScript and React ecosystem. Its core dependencies include:

@rnaga/wp-node — TypeScript-first WordPress database integration.
next — Next.js framework providing SSR, routing, and server functions.
@mui/material — Material UI component library for building the admin interface.
@tiptap/react, mui-tiptap — TipTap rich-text editor with Material UI integration.

Hooks (Filter and Action)

WP-Next uses the WP-Node hook system, which is inspired by WordPress hooks but designed for TypeScript and Node.js. It supports both filters (for transforming data) and actions (for running side effects).

Because WP-Node is TypeScript-first, hooks are:

Type-safe — strongly typed signatures for safer extension.
Asynchronous filters — filters can be async and return transformed data.
Actions as events — actions are built on top of Node.js EventEmitter and are used to trigger side effects.
Independent of PHP — not directly compatible with WordPress core hooks.

Key points:

Filters: transform and return data; may be async.
Actions: perform side effects and do not return data.
Hooks can be registered either with TypeScript decorators (for static / lifecycle hooks) or with the HookCommand utilities (for runtime / dynamic hooks).

For more details about hooks, how they work, and usage examples, see the WP-Node hooks documentation:

https://rnaga.github.io/wp-node/docs/concepts-features/hooks

Frontend vs Backend Hooks

When initialized, WP-Next generates a _wp/hooks directory where you can add your own hooks:

hooks/
├── client
│   └── index.tsx
└── server
    ├── admin-media.hook.ts
    ├── index.ts
    ├── nextauth-providers.hook.ts
    └── notifications.hook.ts

Frontend Hooks

Frontend hooks (under _wp/hooks/client/) are bundled into the Admin UI and run in the browser.

Use them for UI extensions such as:

Adding sidebar menus
Registering custom admin pages
Applying client-side theming

⚠️ Frontend hooks must only contain client-safe code (no filesystem access, no env secrets, no server-only APIs).

Backend Hooks

Backend hooks (under _wp/hooks/server/) run on the server-side application.

Use them for responsibilities like:

Media upload handling
Authentication providers (e.g., NextAuth integration)
Email sending
Other Node.js integrations requiring credentials or server APIs

Conclusion

WP-Next brings the familiar power of WordPress into a Next.js + TypeScript world, giving developers a modern, headless CMS dashboard without the need to work in PHP. With support for posts, pages, media, users, revisions, and even multi-site networks, it provides a solid foundation for building custom admin experiences.

If you’d like to explore further:

⭐ Star the repo on GitHub: https://github.com/rnaga/wp-next
📖 View Full Documentation

Give the quick demo a try, experiment with hooks, and see how WP-Next can fit into your workflow. This is just the beginning — the project will continue to evolve, and community feedback will help shape its future.

WordPress in TypeScript — Build Fast Without PHP

rnaga — Fri, 18 Jul 2025 15:30:00 +0000

WP-Node lets you work directly with your WordPress data — using modern TypeScript and Node.js. No PHP. No WordPress runtime. Just clean APIs for querying posts, users, terms, and metadata, backed by a powerful CLI.

Whether you're building automation scripts, developer tools, or headless apps, WP-Node gives you the flexibility of Node with the structure of WordPress.

👉 View on GitHub

🧩 When You Just Want to Work with WordPress Data

WordPress is one of the most widely used CMS platforms, but its all-in-one architecture often gets in the way for developers who just need to work with the data.

Out of the box, WordPress includes:

A full PHP runtime
Gutenberg block editor
Admin UI and themes

While this is great for editors and site owners, it can feel heavy when you're focused purely on backend or integration work.

Common developer tasks that are harder than they need to be:

🧱 Running wp-cli to inspect data

Requires a full WordPress environment, PHP setup, and deep knowledge of WordPress internals — even for simple scripting tasks.
🪵 Navigating WordPress database by hand

You need to understand internal SQL schema and join behavior — with no typing or IDE support.
🌐 Building modern apps (e.g., Next.js, NestJS for REST API)

You’re stuck either querying MySQL directly or proxying through REST endpoints from WordPress.

🚀 Meet WP-Node

WP-Node is a TypeScript toolkit that lets you interact with your WordPress database directly — without booting up WordPress or writing a single line of PHP.

It gives you a clean, fully-typed interface for querying, inspecting, and manipulating WordPress data using modern Node.js workflows.

🧪 Example: Fetch a Post by ID

With WP-Node, querying WordPress content is straightforward:

import Application from "@rnaga/wp-node/application";

(async () => {
  // Initialize WP-Node application
  const wp = await Application.getContext();

  // Fetch a post with ID 1
  const posts = await wp.utils.query.posts((query) => {
    query.where("ID", 1);
  });

  console.log(posts);
  process.exit(0);
})();

No WordPress bootstrap, no wp-load.php — just clean, TypeScript-native access to your content.

🔧 Key features:

Query core tables like posts, users, terms, comments, and meta
Typed utility classes for common patterns like post & meta access, term relationships
CLI-first mindset comes with built-in CLI commands and makes it easy to define your own custom scripts.
No WordPress runtime required — Doesn’t depend on PHP, themes, plugins, or WordPress bootstrap. Just point it at your existing database.
Modern architecture with decorators and dependency injection
TypeScript + Knex.js + Zod for type-safe, validated, and fluent database access using a modern query builder.

🛠️ Use it for things like:

Running cleanup scripts on postmeta
Building internal admin tools
Creating custom CLI commands (e.g. sync-users, seed-posts)
Integrating with modern apps (Next.js, NestJS, etc.)

WP-Node focuses on what developers care about: structured data access, automation, and developer experience — without the bloat.

⚙️ Getting Started

WP-Node lets you build apps and scripts on top of WordPress data using only Node.js and TypeScript — no WordPress PHP runtime required. Follow these steps to get up and running.

1. Prerequisites

WP-Node requires a MySQL-compatible WordPress database. You can use your existing WordPress setup, or spin up a new one using Docker:

docker network create wpnet && \
docker run -d --name wpdb --network wpnet -p 33306:3306 \
  -e MYSQL_ROOT_PASSWORD=example \
  -e MYSQL_DATABASE=wordpress \
  -e MYSQL_USER=wp \
  -e MYSQL_PASSWORD=wp \
  mariadb && \
docker run -d --name wp --network wpnet -p 8080:80 \
  -e WORDPRESS_DB_HOST=wpdb:3306 \
  -e WORDPRESS_DB_USER=wp \
  -e WORDPRESS_DB_PASSWORD=wp \
  -e WORDPRESS_DB_NAME=wordpress \
  wordpress

Then visit http://localhost:8080 to complete WordPress setup.

2. Initialize WP‑Node Project

mkdir wp-node
cd wp-node
npx @rnaga/wp-node-cli -- init

Follow the prompts to enter your database settings.

✔ Enter your database hostname: · localhost
✔ Enter your database port: · 33306
✔ Enter your database username: · wp
✔ Enter your database password: · **
✔ Enter your database name: · wordpress
✔ Is it a multi-site? · No
✔ Enter your static assets path: · public

Project Structure

After initialization, your project will look like this:

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

Key files

_wp/config/wp.json: Holds configuration for WP-Node such as public path and multisite info. This file is imported by settings.ts.
_wp/settings.ts: Initializes the WP-Node Context, including config, database access and hooks.
index.ts: The main entry point for your WP-Node app. A basic sample is provided.
.env: Stores sensitive environment variables, including your database credentials and other configuration values required at runtime.

3. Run the App

Once the config is initialized, run the app using:

mvn use 22
npx ts-node ./index.ts

If everything is working correctly, you’ll see SQL output like:

select * from `wp_posts` as `posts_5` where `posts_5`.`ID` = 1
[
  {
    ID: 1,
    post_author: 1,
    post_title: 'Hello world!',
    ...
  }
]

6. Use the CLI (Alternative)

You can also use the built-in CLI to query data without writing code:

npx @rnaga/wp-node-cli -- post get 1 -Z table -F ID,post_title,post_type

┌────────────┬────────────────┐
│ (index)    │ Values         │
├────────────┼────────────────┤
│ ID         │ 1              │
│ post_title │ 'Hello world!' │
│ post_type  │ 'post'         │
└────────────┴────────────────┘

Run npx @rnaga/wp-node-cli -- -h to discover all available commands

npx @rnaga/wp-node-cli -- -h

Usage: <command> <subcommand> [options]

Commands:
   blog             Blog commands
   comment          Comment commands
   config           Generate WP config files
   init             Initialize WP with Node. (Generate wp.json and install dependencies)
   install          Initialize a new blog and create a user
   meta             Meta commands (post, comment, blog, term, user, site)
   option           Options commands
   post             Post commands
   repl             Start a REPL
   role             Role commands
   site             Site commands
   term             Term commands
   user             User commands

⭐️ Conclusion

WP-Node gives developers a modern, TypeScript-first way to interact with WordPress data — no PHP, no themes, and no plugin overhead. Whether you're building a script, a custom CLI, or a backend service, WP-Node makes it fast and developer-friendly.

If you found this project useful, please consider giving it a ⭐️ on GitHub:

👉 GitHub: https://github.com/rnaga/wp-node
👉 Documentation https://rnaga.github.io/wp-node/docs/intro

Your support helps others discover the project and keeps the development going!