@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/searchendpoint available for the configured post types - An MCP host that supports MCP Apps (required for the
responsetool UI)
Installation
npm install @elementor/wp-search-mcp
# or
pnpm add @elementor/wp-search-mcp
Dependency: @modelcontextprotocol/sdk ^1.29.0 (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:
- Search — derive 2–3 single-word keyword variations from the user's question (translate to English if needed)
- Read — fetch the 1–3 most relevant articles
- 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