Beehiiv Analytics MCP Server

Instructions

Implementation Reference

• beehiiv_mcp_server.py:120-132 (handler)

  Core handler function in BeehiivAPI class that makes the API request to fetch post details, handling optional expand parameters.

  def get_post_details(
      self, publication_id: str, post_id: str, expand: Optional[List[str]] = None
  ) -> Dict[str, Any]:
      """Get detailed information about a specific post."""
      params = {}
      if expand:
          params["expand"] = expand
  
      data = self._make_request(
          "GET", f"/publications/{publication_id}/posts/{post_id}", params
      )
      return data.get("data", {})

• beehiiv_mcp_server.py:278-310 (schema)

  Input schema definition for the get_post_details tool, specifying required publication_id and post_id, and optional expand array with specific enum values.

  Tool(
      name="get_post_details",
      description="Get detailed information about a specific post",
      inputSchema={
          "type": "object",
          "properties": {
              "publication_id": {
                  "type": "string",
                  "description": "The publication ID",
              },
              "post_id": {
                  "type": "string",
                  "description": "The post ID (e.g., post_00000000-0000-0000-0000-000000000000)",
              },
              "expand": {
                  "type": "array",
                  "items": {
                      "type": "string",
                      "enum": [
                          "stats",
                          "free_web_content",
                          "free_email_content",
                          "free_rss_content",
                          "premium_web_content",
                          "premium_email_content",
                      ],
                  },
                  "description": "Additional data to include in response",
              },
          },
          "required": ["publication_id", "post_id"],
      },
  ),

• beehiiv_mcp_server.py:426-434 (registration)

  Registration and dispatching logic in the call_tool handler that invokes the get_post_details tool when requested.

  elif name == "get_post_details":
      publication_id = arguments["publication_id"]
      post_id = arguments["post_id"]
      expand = arguments.get("expand")
  
      details = client.get_post_details(publication_id, post_id, expand)
      return CallToolResult(
          content=[TextContent(type="text", text=json.dumps(details, indent=2))]
      )

• server.js:94-96 (handler)

  Alternative JS implementation of the post details handler in BeehiivAPI class, making the API request without expand support.

  async getPostDetails(publicationId, postId) {
    return await makeRequest('GET', `${this.baseUrl}/publications/${publicationId}/posts/${postId}`, this.headers);
  }

• server.js:235-250 (schema)

  Input schema for get_post_details in the JS server tools list.

  name: "get_post_details",
  description: "Get detailed information about a specific post",
  inputSchema: {
    type: "object",
    properties: {
      publication_id: {
        type: "string",
        description: "The ID of the publication"
      },
      post_id: {
        type: "string",
        description: "The ID of the post"
      }
    },
    required: ["publication_id", "post_id"]
  }