@elementor/wp-search-mcp

MCP server that lets AI agents search and read published WordPress content, then render answers in an inline MCP App UI.

Overview

WpSearchMcpServer wraps the WordPress REST API and exposes three MCP tools:

| Tool | Purpose | |------|---------| | search | Find published content by keyword | | read | Fetch full rendered HTML for selected articles | | response | Render the final answer in an inline UI card (markdown, media, source links) |

The server also registers MCP App instructions that guide agents through a search → read → response workflow.

Requirements

• A WordPress site with the REST API enabled
• The core /wp/v2/search endpoint available for the configured post types
• An MCP host that supports MCP Apps (required for the response tool UI)

Installation

npm install @elementor/wp-search-mcp
# or
pnpm add @elementor/wp-search-mcp

Peer dependency: @modelcontextprotocol/sdk (installed automatically as a transitive dependency).

Quick start

import { WpSearchMcpServer } from '@elementor/wp-search-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const wpSearch = new WpSearchMcpServer({
  url: 'https://example.com',
  server: {
    name: 'my-wp-search',
    title: 'My Site Docs',
  },
});

const transport = new StdioServerTransport();
await wpSearch.server.connect(transport);

Pass wpSearch.server to any MCP transport your host uses (stdio, SSE, streamable HTTP, etc.).

Configuration

type WpSearchMcpConfig = {
  /** WordPress site root URL, e.g. https://example.com */
  url: string;
  /**
   * Maps search subtype → REST collection segment.
   * Defaults to { post: 'posts' }.
   */
  postTypes?: Record<string, string>;
  server?: {
    name?: string;    // default: 'wp-search'
    version?: string; // default: '1.0.0'
    title?: string;   // default: 'WordPress Search'
  };
};

Post types

postTypes controls which WordPress content types are searched and how read resolves REST paths.

const wpSearch = new WpSearchMcpServer({
  url: 'https://example.com',
  postTypes: {
    post: 'posts',
    page: 'pages',
  },
});

Keys are passed to /wp/v2/search as subtype[] values. Values are the REST collection segments used by /wp/v2/{segment}/{id}.

Tools

search

Searches published content using one or more keywords.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | keywords | string[] | — | 1–3 keyword variations | | perPage | number | 5 | Results per keyword (max 100) |

Returns JSON: [{ id, title, type }, ...]

read

Fetches full rendered content for up to three articles.

| Parameter | Type | Description | |-----------|------|-------------| | articles | { id: number; type: string }[] | 1–3 articles from search results |

Returns JSON: [{ title, content, link }, ...]

type must be one of the keys configured in postTypes.

response

Final step in the agent workflow. Renders the answer in an inline MCP App card above the chat.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | response | string | — | Markdown answer text | | mediaUrls | { url, type }[] | [] | Images, videos, or YouTube embeds | | sourceLinks | { title, url }[] | [] | Attribution links |

type for media: 'image' | 'video' | 'youtube'

Agent workflow

The server injects instructions telling agents to:

1. Search — derive 2–3 single-word keyword variations from the user's question (translate to English if needed)
2. Read — fetch the 1–3 most relevant articles
3. Response — synthesize an answer with markdown, media URLs, and source links

After calling response, the agent should reply with one short sentence pointing at the answer card (e.g. "See the steps above.").

License

MIT