WordPress MCP Server

Instructions

Implementation Reference

• src/index.ts:1393-1439 (handler)

  The main handler function for the 'get-post-stats' tool. It makes an authenticated API request to the WordPress/Jetpack stats endpoint `/sites/{siteId}/stats/post/{postId}`, processes the response (handling total views, timeframe data, or raw JSON), formats it into a markdown text response, and handles errors.

    async ({ siteUrl, username, password, siteId, postId }) => {
      try {
        const postStats = await makeWPRequest<any>({
          siteUrl,
          endpoint: `sites/${siteId}/stats/post/${postId}`,
          auth: { username, password }
        });
        
        // Format will depend on the actual API response
        let statsText;
        
        if (postStats && typeof postStats.views !== 'undefined') {
          statsText = `
  Post #${postId} Stats:
  Total Views: ${postStats.views || 0}
  First View: ${postStats.first_view || "Unknown"}
  Most Recent View: ${postStats.most_recent_view || "Unknown"}
          `.trim();
        } else if (postStats && Array.isArray(postStats.data)) {
          // Handle timeframe data if present
          statsText = `
  Post #${postId} Views Over Time:
  ${postStats.data.map((item: WPPostStatsData) => `${item.period || "Unknown"}: ${item.views || 0} views`).join('\n')}
          `.trim();
        } else {
          statsText = `Post #${postId} Stats:\n${JSON.stringify(postStats, null, 2)}`;
        }
        
        return {
          content: [
            {
              type: "text",
              text: statsText,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving post stats: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    }

• src/index.ts:1386-1392 (schema)

  Zod input schema defining the required parameters for the get-post-stats tool: siteUrl (URL), username (string), password (string), siteId (number), postId (number). Used for validation by the MCP server.

  {
    siteUrl: z.string().url().describe("WordPress site URL"),
    username: z.string().describe("WordPress username"),
    password: z.string().describe("WordPress application password"),
    siteId: z.number().describe("WordPress site ID"),
    postId: z.number().describe("Post ID to get stats for"),
  },

• src/index.ts:1383-1440 (registration)

  The server.tool() registration call that defines and registers the 'get-post-stats' tool with the MCP server, including its name, description, input schema, and handler function.

  server.tool(
    "get-post-stats",
    "View a specific post's views",
    {
      siteUrl: z.string().url().describe("WordPress site URL"),
      username: z.string().describe("WordPress username"),
      password: z.string().describe("WordPress application password"),
      siteId: z.number().describe("WordPress site ID"),
      postId: z.number().describe("Post ID to get stats for"),
    },
    async ({ siteUrl, username, password, siteId, postId }) => {
      try {
        const postStats = await makeWPRequest<any>({
          siteUrl,
          endpoint: `sites/${siteId}/stats/post/${postId}`,
          auth: { username, password }
        });
        
        // Format will depend on the actual API response
        let statsText;
        
        if (postStats && typeof postStats.views !== 'undefined') {
          statsText = `
  Post #${postId} Stats:
  Total Views: ${postStats.views || 0}
  First View: ${postStats.first_view || "Unknown"}
  Most Recent View: ${postStats.most_recent_view || "Unknown"}
          `.trim();
        } else if (postStats && Array.isArray(postStats.data)) {
          // Handle timeframe data if present
          statsText = `
  Post #${postId} Views Over Time:
  ${postStats.data.map((item: WPPostStatsData) => `${item.period || "Unknown"}: ${item.views || 0} views`).join('\n')}
          `.trim();
        } else {
          statsText = `Post #${postId} Stats:\n${JSON.stringify(postStats, null, 2)}`;
        }
        
        return {
          content: [
            {
              type: "text",
              text: statsText,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving post stats: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    }
  );

• src/index.ts:158-194 (helper)

  The makeWPRequest helper function used by the get-post-stats handler (and other tools) to make authenticated HTTP requests to WordPress REST API endpoints using axios, with Basic Auth and error handling.

  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;
    }
  }

• src/index.ts:140-144 (schema)

  TypeScript interface defining the structure of post stats data points (period and views), referenced in the handler for processing timeframe data.

  interface WPPostStatsData {
    period: string;
    views: number;
  }