WordPress Headless

wp-headless-mcp

AI アシスタントが WordPress サイトのコンテンツを読み取り、安全な編集を支援できる MCP サーバーです。

企業の WordPress サイト（ページ、投稿、プロジェクトやサービスなどのカスタム投稿タイプ、ACF フィールド、Yoast SEO データ）を、Claude などの AI クライアントに接続します。これにより、サイトについて質問したり、平易な言葉でコンテンツについて支援を受けたりできます。

ステータス： 初版の機能がすべて実装されており、実際の WordPress サイトでテスト済みです。ユニットテストは 120 件あります。

---

MCP とは？

Model Context Protocol は、AI アシスタントをデータやツールに接続するためのオープン標準です。MCP サーバーは、以下のような機能を定義します。

• ツール： 「サイトを検索する」や「最近のプロジェクトを一覧表示する」など、AI が呼び出せるアクションです。
• リソース： 特定のページやサイトのコンテンツモデルなど、AI が読み取れるコンテンツです。
• プロンプト： 「このページの SEO をレビューする」など、再利用可能なタスクのテンプレートです。

MCP 対応クライアント（Claude Desktop、Claude Code、Claude API など）は、カスタム連携を構築しなくても同じサーバーを利用できます。

解決する課題

多くの企業は、サービス、事例、チームメンバー、FAQ、製品などのウェブサイトのコンテンツをすでに WordPress で管理しています。その上に Progressive Web App（PWA） のような新しいものを構築する際、コンテンツには次のような課題があります。

• AI が利用しにくい。 チャットボットやアシスタントには、推測ではなく、根拠に基づいた最新の回答が必要です。LLM を WordPress REST API に手作業で接続するのは、繰り返しの多い作業で、間違いも起こりやすくなります。
• 管理画面の中に閉じ込められている。 コンテンツやマーケティングの担当者は、「メタディスクリプションがないページはどれ？」や「新しいサービスについての投稿を下書きして」といった依頼を手軽に行えません。
• 開発者向けのドキュメントがない。 PWA の開発者は、試行錯誤しながら投稿タイプ、ACF フィールドの構造、REST のペイロードを調べなければなりません。

wp-headless-mcp は、こうしたすべての人に、明確に定義された安全な AI ゲートウェイを提供します。

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)

PWA は通常の画面では引き続き WordPress から直接コンテンツを読み込みます。MCP サーバーはその隣で動作し、AI 機能とサイト周辺のツールを支えます。

対象ユーザー

ウェブサイトの訪問者（PWA 経由）

PWA 内の AI アシスタントが、企業独自のコンテンツを使って質問に回答し、情報源となるページへのリンクを提示します。

• 「プロダクトデザインではどのようなサービスを提供していますか？」
• 「小売企業向けに手がけたプロジェクトを見せてください。」
• 「問い合わせるにはどうすればよいですか？」

公開済みの一般公開コンテンツのみを参照し、コンテンツを変更することはできません。

コンテンツ・マーケティングチーム

スタッフは Claude Desktop をサイトに接続し、会話形式でコンテンツを扱えます。

• 「アイキャッチ画像または SEO の説明が不足しているプロジェクトはどれですか？」
• 「最新のプロジェクトについて、ほかの事例と同じスタイルでケーススタディを下書きして。」
• 「Acme プロジェクトのサブタイトルを更新して。」（レビュー用の下書きとして保存）

変更は常に下書きまたはレビュー待ちとして保存されます。AI がコンテンツを公開または削除することはありません。

PWA 開発者

開発者は PWA の構築中に Claude Code を接続します。

• 「このサイトにはどのような投稿タイプと ACF フィールドがありますか？」
• 「ACF フィールドを含む、プロジェクト投稿タイプの TypeScript 型を生成して。」
• 「プロジェクトの REST ペイロードのサンプルを見せて。」
• 「このサイトはヘッドレス利用の要件を満たしていますか？」

エージェンシーとフリーランサー

このサーバーは特定のウェブサイトに限定されません。サイト要件を満たす任意の WordPress サイトに接続して、クライアント向けに AI 機能を追加したり、コンテンツを監査したり、ヘッドレス構築を効率化したりできます。クライアントのプロジェクトについてサポートが必要ですか？セットアップとカスタム作業をご覧ください。

提供する機能

領域	機能	プロファイル
コンテンツ	ACF フィールドを含むサイト全体の検索、投稿、固定ページ、カスタム投稿タイプの取得や一覧表示、カテゴリーとタグ、Markdown 出力	すべて
ACF	acf-json のラベルとタイプを含む、あらゆる項目のカスタムフィールド値	すべて
会社情報	サイト名、キャッチフレーズ、組織の詳細、ソーシャルプロフィール（Yoast から取得）、ホームページのテキスト	すべて
SEO	Yoast のタイトル、説明、canonical URL、ソーシャル画像、ページごとのレビュー、サイト全体の問題スキャン	すべて（Yoast が有効な場合）
編集	下書きの作成と更新、公開済み項目の下書きへのコピー、ACF フィールドの更新、メディアのアップロード、下書きの一覧表示	editor
監査	アイキャッチ画像、代替テキスト、メタディスクリプション、抜粋の欠落、および古いコンテンツ	editor
開発者ツール	コンテンツモデル、ACF スキーマ、ペイロードのサンプル、TypeScript 型生成、サイト要件とヘルスチェック	dev
プロンプト	訪問者への回答、SEO レビュー、ブログの下書き作成、週次コンテンツレポート	すべて / editor

アクセスプロファイル

1 つのサーバーに 3 つのプロファイルがあります。プロファイルによって利用可能なツール自体が決まるため、公開環境で編集ツールが誤って公開されることはありません。

プロファイル	対象	できること
public	PWA の AI アシスタント	公開済みコンテンツの読み取り。認証情報が設定されていても、サインインは行いません
editor	コンテンツおよびマーケティングチーム	読み取りに加え、下書きの作成と更新、監査、メニューの操作（メニューには Administrator 権限が必要）
dev	開発者	読み取りに加え、スキーマ、型生成、ペイロードのサンプル、サイトチェック

editor と dev のプロファイルは、WordPress の アプリケーションパスワード を使ってサインインするため、WordPress 自体のユーザーロールと権限が引き続き適用されます。サーバーは起動時にログインとユーザーの権限を確認します。

設計原則

• プラグインは不要です。 サーバーは標準の WordPress REST API のみを読み取るため、クライアントのサイトに追加でインストールするものはありません。
• デフォルトで安全です。 公開環境では読み取り専用です。編集者が扱えるのは下書きのみです。公開済みの項目は変更できず、レビュー用に下書きへコピーすることだけができます。削除操作はありません。
• 根拠に基づく回答です。 ツールは情報の出典を AI が引用できるよう、ソース URL を返します。
• 簡潔でクリーンな応答です。 HTML は Markdown に変換され、使用されないメタデータは削除されるため、AI の応答を高速かつ低コストに保てます。
• さまざまなサイトで動作します。 投稿タイプと REST ルートはハードコードせず、自動的に検出します。Yoast SEO などのオプションの連携機能は、サイトに導入されている場合にのみ表示されます。

サイト要件

WordPress サイトを十分に活用するには、次の条件を満たす必要があります。

1. AI クライアントに表示するカスタム投稿タイプを、show_in_rest => true を指定して登録します。
2. ACF フィールドグループをテーマの acf-json フォルダーに保存します。
3. 公開コンテンツを保持する ACF フィールドグループでは、**「Show in REST API」**を有効にします。
4. エディターと dev プロファイルでは、アプリケーションパスワード（WordPress のデフォルト）を有効にしておきます。Wordfence などのセキュリティプラグインによって無効になる場合があります。

dev プロファイルの check_site_requirements ツールで、これらの要件を確認できます。

既知の制限事項： ACF オプションページ（電話番号やメールアドレスなどのサイト全体の設定）は REST API からアクセスできません。また、メニューにはサインイン済みの管理者が必要です。

はじめに

必要要件：Node.js 22 以降、および REST API にアクセスできる WordPress サイト。

インストールは不要です。MCP クライアントは npx -y wp-headless-mcp でサーバーを起動し、設定を環境変数として渡します。少なくとも WP_URL を設定してください。エディターまたは dev プロファイルを使用する場合は、アプリケーションパスワードも作成し（wp-admin → Users → Profile → Application Passwords。エディター権限を持つ専用ユーザーの使用を推奨）、WP_USER と WP_APP_PASSWORD を設定してください。すべての設定については、設定をご覧ください。

このサーバーは、MCP Registryにも io.github.aj-ua/wp-headless-mcp として掲載されています。

MCP Inspector で試す

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

Inspector がブラウザーで開きます。「Connect」をクリックして、ツール、リソース、プロンプトを試してください。

Claude Code に接続する

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

編集用ツールを使うには、-e MCP_PROFILE=editor -e WP_USER=... -e WP_APP_PASSWORD=... を追加してください。

Claude Desktop に接続する

サーバーを ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）に追加し、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"
      }
    }
  }
}

PWA バックエンドに接続する

サーバーを HTTP モードで実行し、バックエンドから呼び出します。セットアップ、セキュリティ、実行可能な Claude API の例については、docs/PWA_BACKEND.mdをご覧ください。

設定

すべての設定は環境変数で行います。MCP クライアントはサーバーの起動時にこれらを渡します（Claude Code では -e、Claude Desktop では env）。ソースから実行する場合、npm スクリプトも .env を読み込みます。

変数	デフォルト	用途
WP_URL	必須	サイトのベース URL。例：http://aj-ua.local
WP_USER	—	Application Password のユーザー（editor および dev プロファイル）
WP_APP_PASSWORD	—	Application Password
MCP_PROFILE	public	public、editor、または dev
WP_CACHE_TTL	60	GET リクエストをキャッシュする秒数。0 にするとキャッシュが無効になります
ACF_JSON_PATH	—	ACF のラベル、スキーマ、TypeScript 型定義に使用する、テーマの acf-json フォルダーへのパス
MCP_CPTS	auto	カスタム投稿タイプのツール：auto、none、または [{"postType":"project","singular":"project","plural":"projects"}] のような JSON
MCP_TRANSPORT	stdio	ローカルクライアントには stdio、リモートクライアントには http
MCP_HTTP_TOKEN	—	HTTP モード用の Bearer トークン。32 文字以上（openssl rand -hex 32）
MCP_HTTP_HOST	127.0.0.1	HTTP のバインドアドレス。HTTPS リバースプロキシの背後でのみ 0.0.0.0 を使用してください
MCP_HTTP_PORT	3333	HTTP ポート
MCP_HTTP_SESSIONS	false	true にするとクライアントごとに 1 つのセッションを維持します。デフォルトはステートレスです
MCP_HTTP_SESSION_IDLE_MINUTES	30	アイドル状態のセッションのタイムアウト
MCP_HTTP_ALLOWED_ORIGINS	—	CORS で許可するブラウザーのオリジンをカンマ区切りで指定します。空の場合、サーバー間通信のみを許可します

リファレンス

ツール

すべてのプロファイル：

ツール	説明
list_post_types	公開件数とタクソノミーを含むコンテンツタイプ
search_content	キーワード検索。WordPress 検索の results と ACF フィールドの acf_matches を返します
list_posts / get_post	任意の投稿タイプを一覧表示または読み込みます。本文は Markdown 形式で、ACF フィールド、アイキャッチ画像、タームも含みます
list_<type> / get_<type>	カスタム投稿タイプごとに生成されます。例：list_projects、get_project
list_terms	カテゴリー、タグ、カスタムタクソノミーのターム
get_acf_fields	1 件の ACF 値をラベル、タイプ、フィールドグループとともに取得します
get_company_info	サイト、組織、ソーシャルプロフィール、ホームページのテキスト
get_seo_meta	1 件のアイテムまたは URL の Yoast SEO データと問題（Yoast のみ）
find_seo_issues	サイト全体の SEO スキャンと問題ごとの件数（Yoast のみ）

editor プロファイル：

ツール	説明
create_draft	新しい下書きを作成します。既存のアイテムからコピーすることもできます（copy_from）
update_post	下書きまたはレビュー待ちのアイテムを変更します。レビューに提出することもできます
update_acf_fields	下書きまたはレビュー待ちのアイテムの ACF 値を設定し、フィールドグループに照らして検証します
list_drafts	編集リンク付きで下書きとレビュー待ちのアイテムを一覧表示します
upload_media	公開 URL から代替テキスト付きの画像または PDF を追加します
content_audit	画像、代替テキスト、説明、抜粋の不足、および古いコンテンツを確認します
get_menu	ナビゲーションメニューをツリー形式で取得します（管理者のみ）

dev プロファイル：

ツール	説明
describe_content_model	投稿タイプ、REST ルート、タクソノミーフィールド、タイプごとの ACF グループ
get_acf_schema	ACF フィールド定義全体
sample_payload	コンテンツルートの REST JSON 生データ
generate_ts_types	投稿タイプの TypeScript インターフェース。ACF 形式は standard または light
check_site_requirements	上記のサイト要件を確認します
site_health	WordPress のバージョン、名前空間、プラグイン、HTTPS、タイムゾーン、PWA オリジンの CORS

リソース

URI	内容
wp://site/info	サイト、組織、投稿タイプ、タクソノミー、検出された機能（JSON）
wp://post/{type}/{id}	ACF フィールドを含む、1 件のアイテムの Markdown 形式
wp://page/{slug}	ACF フィールドを含む、1 ページの Markdown 形式

プロンプト

プロンプト	プロファイル	機能
answer_visitor_question	すべて	サイトのコンテンツのみを参照し、リンク付きで回答します
seo_review	すべて（Yoast のみ）	1 つの項目をレビューし、修正案を提案します
write_blog_draft	editor	サイトのスタイルに沿って記事を作成し、下書きとして保存します
weekly_content_report	editor	最近の変更、レビュー待ちの下書き、主な問題をまとめます

開発

ソースから実行

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

.env を編集し、少なくとも WP_URL を設定します。npm start、npm run dev、npm run inspect はこのファイルを読み込みます。ローカルビルドに MCP クライアントを接続するには、npx -y wp-headless-mcp の代わりに node /absolute/path/to/wp-headless-mcp/dist/index.js を使用し、設定を環境変数として渡します。

スクリプト

コマンド	機能
npm run dev	tsx を使ってソースから実行します（stdio）
npm run build / npm start	dist/ にコンパイルして実行します
npm run inspect	ソースに対して MCP Inspector を開きます
npm test	単体テスト（vitest）。ネットワークは不要です
npm run lint / npm run format	ESLint と Prettier
npm run check	CI で実行するすべてのチェック：型チェック、リント、フォーマット、テスト
npm run example:client -- "<question>"	サーバー経由で Claude に質問します（docs/PWA_BACKEND.md）

テストでは、tests/fixtures/ に記録された aj-ua のレスポンスを使用します。ビルドと型チェックでは TypeScript 7（typescript7 としてインストール）を使用します。TypeScript 6.0 もインストールされますが、ESLint と型生成テスト専用です。これは、typescript-eslint と TypeScript の JavaScript API がまだ TypeScript 7 をサポートしていないためです。

ロードマップ

• typescript-eslint が TypeScript 7 をサポートしたら、TypeScript 6.0.3 のコピーを削除します。
• サーバーがパブリックな HTTPS アドレスで稼働したら、Claude の MCP コネクターをテストします（オプション A）。

技術スタック

• Node.js 22 上の TypeScript
• @modelcontextprotocol/sdk と zod
• HTML から Markdown への変換に turndown
• WordPress REST API（コア、ACF、Yoast）
• vitest、ESLint（typescript-eslint）、Prettier

セットアップとカスタム開発

wp-headless-mcp を開発・保守しており、関連する有償の業務を承っています。

• セットアップ： サーバーを WordPress サイトに接続し、投稿タイプと ACF フィールドをマッピングして、アクセスプロファイルを設定します。
• カスタムツール： サイトのコンテンツモデルやワークフローに合わせて、ツール、リソース、プロンプトを追加します。
• PWA 向け AI 機能： 独自のコンテンツをもとに訪問者の質問に回答するアシスタントを構築します。
• チームへの導入支援： コンテンツチームが Claude Desktop で日々活用できるよう支援します。

aj-ua.com または LinkedIn からお問い合わせください。

ライセンス

MIT