WordPress MCP Server

Instructions

Implementation Reference

• src/index.ts:601-699 (handler)

  The main handler function that executes the list-posts tool: constructs API parameters from inputs, calls the WordPress REST API /posts endpoint, formats the WPPost objects into a readable list, and returns a text response.
  async ({ siteUrl, username, password, context, page, perPage, search, after, modifiedAfter, author, authorExclude, before, modifiedBefore, exclude, include, offset, order, orderby, searchColumns, slug, status, taxRelation, categories, categoriesExclude, tags, tagsExclude, sticky, }) => { try { const params: Record<string, any> = { context, page, per_page: perPage, order, orderby, status: status?.join(','), }; if (search) params.search = search; if (after) params.after = after; if (modifiedAfter) params.modified_after = modifiedAfter; if (author) params.author = author.join(','); if (authorExclude) params.author_exclude = authorExclude.join(','); if (before) params.before = before; if (modifiedBefore) params.modified_before = modifiedBefore; if (exclude) params.exclude = exclude.join(','); if (include) params.include = include.join(','); if (offset) params.offset = offset; if (searchColumns) params.search_columns = searchColumns.join(','); if (slug) params.slug = slug.join(','); if (taxRelation) params.tax_relation = taxRelation; if (categories) params.categories = categories.join(','); if (categoriesExclude) params.categories_exclude = categoriesExclude.join(','); if (tags) params.tags = tags.join(','); if (tagsExclude) params.tags_exclude = tagsExclude.join(','); if (sticky !== undefined) params.sticky = sticky; const posts = await makeWPRequest<WPPost[]>({ siteUrl, endpoint: "posts", auth: { username, password }, params }); const formattedPosts = Array.isArray(posts) ? posts.map(post => ({ id: post.id, title: post.title?.rendered || "No title", date: post.date || "No date", status: post.status || "unknown", author: post.author || "Unknown", excerpt: post.excerpt?.rendered || "No excerpt" })) : []; const postsText = formattedPosts.length > 0 ? formattedPosts.map(post => `ID: ${post.id}\nTitle: ${post.title}\nDate: ${post.date}\nStatus: ${post.status}\nAuthor: ${post.author}\nExcerpt: ${post.excerpt}\n---` ).join("\n") : "No posts found"; return { content: [ { type: "text", text: `Posts from ${siteUrl}:\n\n${postsText}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving posts: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }
• src/index.ts:572-600 (schema)

  Zod schema for input validation of the list-posts tool, supporting comprehensive WordPress post filtering (pagination, search, date ranges, authors, categories, tags, status, etc.).
  { siteUrl: z.string().url().describe("WordPress site URL"), username: z.string().describe("WordPress username"), password: z.string().describe("WordPress application password"), context: z.enum(["view", "embed", "edit"]).optional().default("view").describe("Scope under which the request is made"), page: z.number().min(1).optional().default(1).describe("Current page of the collection"), perPage: z.number().min(1).max(100).optional().default(10).describe("Maximum number of items to be returned"), search: z.string().optional().describe("Limit results to those matching a string"), after: z.string().optional().describe("Limit response to posts published after a given ISO8601 compliant date"), modifiedAfter: z.string().optional().describe("Limit response to posts modified after a given ISO8601 compliant date"), author: z.array(z.number()).optional().describe("Limit result set to posts assigned to specific authors"), authorExclude: z.array(z.number()).optional().describe("Ensure result set excludes posts assigned to specific authors"), before: z.string().optional().describe("Limit response to posts published before a given ISO8601 compliant date"), modifiedBefore: z.string().optional().describe("Limit response to posts modified before a given ISO8601 compliant date"), exclude: z.array(z.number()).optional().describe("Ensure result set excludes specific IDs"), include: z.array(z.number()).optional().describe("Limit result set to specific IDs"), offset: z.number().optional().describe("Offset the result set by a specific number of items"), order: z.enum(["asc", "desc"]).optional().default("desc").describe("Order sort attribute ascending or descending"), orderby: z.enum(["author", "date", "id", "include", "modified", "parent", "relevance", "slug", "include_slugs", "title"]).optional().default("date").describe("Sort collection by post attribute"), searchColumns: z.array(z.string()).optional().describe("Array of column names to be searched"), slug: z.array(z.string()).optional().describe("Limit result set to posts with one or more specific slugs"), status: z.array(z.enum(["publish", "future", "draft", "pending", "private"])).optional().default(["publish"]).describe("Limit result set to posts assigned one or more statuses"), taxRelation: z.enum(["AND", "OR"]).optional().describe("Limit result set based on relationship between multiple taxonomies"), categories: z.array(z.number()).optional().describe("Limit result set to items with specific terms assigned in the categories taxonomy"), categoriesExclude: z.array(z.number()).optional().describe("Limit result set to items except those with specific terms assigned in the categories taxonomy"), tags: z.array(z.number()).optional().describe("Limit result set to items with specific terms assigned in the tags taxonomy"), tagsExclude: z.array(z.number()).optional().describe("Limit result set to items except those with specific terms assigned in the tags taxonomy"), sticky: z.boolean().optional().describe("Limit result set to items that are sticky"), },
• src/index.ts:569-571 (registration)

  MCP server registration of the 'list-posts' tool, specifying name, description, input schema, and handler function.
  server.tool( "list-posts", "Get a list of posts with comprehensive filtering options",
• src/index.ts:10-57 (helper)

  TypeScript interface defining the structure of WordPress post objects returned by the API and used in the handler.
  interface WPPost { id: number; date?: string; date_gmt?: string; guid?: { rendered: string; }; modified?: string; modified_gmt?: string; slug?: string; status?: 'publish' | 'future' | 'draft' | 'pending' | 'private'; type?: string; link?: string; title?: { rendered: string; }; content?: { rendered: string; protected?: boolean; }; excerpt?: { rendered: string; protected?: boolean; }; author?: number; featured_media?: number; comment_status?: 'open' | 'closed'; ping_status?: 'open' | 'closed'; sticky?: boolean; template?: string; format?: 'standard' | 'aside' | 'chat' | 'gallery' | 'link' | 'image' | 'quote' | 'status' | 'video' | 'audio'; meta?: Record<string, any>; _links?: { self?: Array<{ href: string }>; collection?: Array<{ href: string }>; about?: Array<{ href: string }>; author?: Array<{ href: string; embeddable: boolean }>; replies?: Array<{ href: string; embeddable: boolean }>; 'version-history'?: Array<{ href: string }>; 'predecessor-version'?: Array<{ href: string; id: number }>; 'wp:featuredmedia'?: Array<{ href: string; embeddable: boolean }>; 'wp:attachment'?: Array<{ href: string }>; 'wp:term'?: Array<{ href: string; taxonomy: string; embeddable: boolean }>; curies?: Array<{ name: string; href: string; templated: boolean }>; }; categories?: number[]; tags?: number[]; }
• src/index.ts:158-194 (helper)

  Reusable helper function for authenticated HTTP requests to the WordPress REST API v2, used by all tools including list-posts.
  async function makeWPRequest<T>({ siteUrl, endpoint, method = 'GET', auth, data = null, params = null }: { siteUrl: string; endpoint: string; method?: 'GET' | 'POST' | 'PUT' | 'DELETE'; auth: { username: string; password: string }; data?: any; params?: any; }): Promise<T> { const authString = Buffer.from(`${auth.username}:${auth.password}`).toString('base64'); try { const response = await axios({ method, url: `${siteUrl}/wp-json/wp/v2/${endpoint}`, headers: { 'Authorization': `Basic ${authString}`, 'Content-Type': 'application/json', }, data: data, params: params }); return response.data as T; } catch (error) { if (axios.isAxiosError(error) && error.response) { throw new Error(`WordPress API error: ${error.response.data?.message || error.message}`); } throw error; } }