wp-headless-mcp

An MCP server that lets AI assistants read, and safely help edit, the content of a WordPress website.

It connects a company's WordPress site (pages, posts, custom post types like projects or services, ACF fields, and Yoast SEO data) to AI clients such as Claude. Then people can ask questions about the site, or get help with its content, in plain language.

Status: feature-complete for its first version and tested against a real WordPress site, with 120 unit tests.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to data and tools. An MCP server describes what it can do as:

• Tools: actions the AI can call, like "search the site" or "list recent projects".

• Resources: content the AI can read, like a specific page or the site's content model.

• Prompts: reusable task templates, like "review this page's SEO".

Any MCP-compatible client (Claude Desktop, Claude Code, the Claude API, and others) can use the same server without custom integration work.

Related MCP server: wp-mcp

The problem it solves

Many companies already keep their website content in WordPress: services, case studies, team members, FAQs, products. When they build something new on top of it, like a Progressive Web App (PWA), that content is often:

• Hard for AI to use. A chatbot or assistant needs grounded, current answers, not guesses. Wiring an LLM to the WordPress REST API by hand is repetitive and easy to get wrong.

• Locked behind admin screens. Content and marketing staff can't quickly ask "which pages have no meta description?" or "draft a post about our new service".

• Undocumented for developers. PWA developers have to discover post types, ACF field structures, and REST payloads by trial and error.

wp-headless-mcp gives all of these people one well-defined, safe AI gateway to the site.

How it fits with a PWA

                    ┌────────────────────────────┐
                    │     WordPress website      │
                    │  pages · projects · ACF ·  │
                    │  · Yoast SEO               │
                    └─────────────┬──────────────┘
                                  │ REST API
              ┌───────────────────┴───────────────────┐
              │                                       │
     PWA user interface                        wp-headless-mcp
  (reads REST API directly:                  (AI layer: tools,
   pages, lists, images)                     resources, prompts)
                                                      │
                               ┌──────────────────────┼──────────────────────┐
                               │                      │                      │
                      AI assistant in the PWA   Content team in      Developers in
                      (via the PWA backend      Claude Desktop       Claude Code
                       and the Claude API)

The PWA keeps reading content from WordPress directly for its normal screens. The MCP server sits next to it and powers the AI features, plus the tools around the site.

Who it's for

Website visitors (through the PWA)

An AI assistant inside the PWA that answers questions using the company's own content and links to the source page.

• "What services do you offer for product design?"

• "Show me projects you've done for retail companies."

• "How can I get in touch?"

It only sees published, public content and can't change anything.

Content and marketing team

Staff connect Claude Desktop to the site and work with content conversationally.

• "Which projects are missing a featured image or SEO description?"

• "Draft a case study for our latest project in the same style as the others."

• "Update the subtitle on the Acme project." (saved as a draft for review)

Changes are always saved as drafts or pending review. The AI never publishes or deletes content.

PWA developers

Developers connect Claude Code while building the PWA.

• "What post types and ACF fields does this site have?"

• "Generate TypeScript types for the project post type, including its ACF fields."

• "Show me a sample REST payload for a project."

• "Does this site meet the requirements for headless use?"

Agencies and freelancers

The server isn't tied to one website. Point it at any WordPress site that meets the site requirements to add AI features for a client, audit content, or speed up headless builds. Need help with a client project? See setup and custom work.

What it offers

Access profiles

One server, three profiles. The profile decides which tools exist at all, so a public deployment can't expose editing tools even by mistake.

The editor and dev profiles sign in with a WordPress Application Password, so WordPress's own user roles and permissions still apply. The server checks the login and the user's capabilities at startup.

Design principles

• No plugin required. The server reads only the standard WordPress REST API, so nothing extra needs installing on the client's site.

• Safe by default. Read-only for the public. Drafts only for editors: published items can't be changed, only copied into a draft for review. No delete actions anywhere.

• Grounded answers. Tools return source URLs so the AI can cite where information came from.

• Small, clean responses. HTML is converted to Markdown and unused metadata is removed, which keeps AI responses fast and inexpensive.

• Works across sites. Post types and REST routes are discovered automatically, not hardcoded. Optional integrations such as Yoast SEO only appear when the site has them.

Site requirements

To work fully, a WordPress site should:

1. Register custom post types that AI clients should see with show_in_rest => true.

2. Save ACF field groups to the theme's acf-json folder.

3. Turn on "Show in REST API" for ACF field groups that hold public content.

4. Keep Application Passwords enabled (the WordPress default) for the editor and dev profiles. Security plugins such as Wordfence can turn them off.

The dev profile's check_site_requirements tool checks these for you.

Known limits: ACF options pages (site-wide settings like phone and email) aren't reachable through the REST API, and menus need a signed-in Administrator.

Getting started

Requirements: Node.js 22 or newer, and a WordPress site whose REST API is reachable.

There's nothing to install: MCP clients start the server with npx -y wp-headless-mcp and pass the settings as environment variables. Set at least WP_URL. For the editor or dev profile, also create an Application Password (wp-admin → Users → Profile → Application Passwords, ideally for a dedicated user with the Editor role) and set WP_USER and WP_APP_PASSWORD. All settings: Configuration.

The server is also listed in the MCP Registry as io.github.aj-ua/wp-headless-mcp.

Try it in the MCP Inspector

npx @modelcontextprotocol/inspector -e WP_URL=http://aj-ua.local -- npx -y wp-headless-mcp

The Inspector opens in the browser. Click Connect, then try the tools, resources, and prompts.

Connect Claude Code

claude mcp add wp-headless-mcp -e WP_URL=http://aj-ua.local -- npx -y wp-headless-mcp

Add -e MCP_PROFILE=editor -e WP_USER=... -e WP_APP_PASSWORD=... for the editing tools.

Connect Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then restart Claude Desktop:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "wp-headless-mcp"],
      "env": {
        "WP_URL": "http://aj-ua.local",
        "MCP_PROFILE": "editor",
        "WP_USER": "mcp-editor",
        "WP_APP_PASSWORD": "<application password>",
        "ACF_JSON_PATH": "/absolute/path/to/wp-content/themes/your-theme/acf-json"
      }
    }
  }
}

Connect a PWA backend

Run the server in HTTP mode and call it from the backend. Setup, security, and runnable Claude API examples: docs/PWA_BACKEND.md.

Configuration

All settings are environment variables. MCP clients pass them when they start the server (-e in Claude Code, env in Claude Desktop). When running from source, the npm scripts also read .env.

Reference

Tools

All profiles:

editor profile:

dev profile:

Resources

Prompts

Development

Run from source

git clone https://github.com/aj-ua/wp-headless-mcp.git
cd wp-headless-mcp
npm install
cp .env.example .env
npm run build

Edit .env and set at least WP_URL. npm start, npm run dev, and npm run inspect read it. To connect an MCP client to your local build, use node /absolute/path/to/wp-headless-mcp/dist/index.js in place of npx -y wp-headless-mcp, and pass the settings as environment variables.

Scripts

The tests use recorded aj-ua responses in tests/fixtures/. Build and type checks use TypeScript 7 (installed as typescript7). TypeScript 6.0 is also installed, only for ESLint and the type-generator test, because typescript-eslint and TypeScript's JavaScript API don't support TypeScript 7 yet.

Roadmap

• Remove the TypeScript 6.0.3 copy once typescript-eslint supports TypeScript 7.

• Test Claude's MCP connector (option A) once the server runs at a public HTTPS address.

Tech stack

• TypeScript on Node.js 22

• @modelcontextprotocol/sdk and zod

• turndown for HTML to Markdown

• WordPress REST API (core, ACF, Yoast)

• vitest, ESLint (typescript-eslint), and Prettier

Setup and custom work

I build and maintain wp-headless-mcp, and I'm available for paid work around it:

• Setup: connect the server to your WordPress site, map your post types and ACF fields, and configure access profiles.

• Custom tools: add tools, resources, or prompts for your site's content model and workflows.

• AI features for your PWA: build an assistant that answers visitors' questions from your own content.

• Team onboarding: help your content team use it day to day in Claude Desktop.

Get in touch through aj-ua.com or LinkedIn.

License

MIT