Beehiiv MCP Server

Instructions

Retrieve a post's content as JSON to use as a template.

Args:
    publication_id: ID of the publication
    post_id: ID of the post

Returns:
    dict: JSON object containing post title, subtitle, and HTML content template

Implementation Reference

• beehiiv_server.py:104-136 (handler)

  The main handler function for the 'get_post_content' tool. It fetches the post content from the Beehiiv API using the provided publication_id and post_id, extracts title, subtitle, content_structure, and HTML template from the free web content, and returns them as a dictionary. Uses the beehiiv_request helper.

  @mcp.tool()
  async def get_post_content(publication_id: str, post_id: str) -> dict:
      """
      Retrieve a post's content as JSON to use as a template.
  
      Args:
          publication_id: ID of the publication
          post_id: ID of the post
      
      Returns:
          dict: JSON object containing post title, subtitle, and HTML content template
      """
      path = f"/publications/{publication_id}/posts/{post_id}"
      params = {
          "expand[]": "free_web_content"
      }
      
      data = await beehiiv_request("GET", path, params=params)
      
      if not data or "data" not in data:
          return {"error": "Failed to fetch the post."}
      
      post = data["data"]
      content = post.get("content", {})
      free_content = content.get("free", {})
      
      return {
          "title": post.get("title"),
          "subtitle": post.get("subtitle"),
          "content_structure": post.get("content_structure"),
          "html_template": free_content.get("web")
      }

• beehiiv_server.py:104-104 (registration)

  The @mcp.tool() decorator registers the get_post_content function as an MCP tool.

  @mcp.tool()

• beehiiv_server.py:17-50 (helper)

  Helper function used by get_post_content to make authenticated API requests to Beehiiv.

  async def beehiiv_request(
      method: str,
      path: str,
      params: Optional[dict[str, Any]] = None,
      json_body: Optional[dict[str, Any]] = None
  ) -> Optional[dict[str, Any]]:
      """
      Helper to call the beehiiv API v2.
  
      Args:
          method: HTTP method (GET, POST, etc.)
          path:   API path (e.g. '/publications')
          params: Query parameters
          json_body: Request JSON body
      """
      headers = {
          "Authorization": f"Bearer {BEEHIIV_API_KEY}",
          "Content-Type": "application/json"
      }
      url = f"{BASE_URL}{path}"
      async with httpx.AsyncClient() as client:
          try:
              response = await client.request(
                  method, url,
                  headers=headers,
                  params=params,
                  json=json_body,
                  timeout=30.0
              )
              response.raise_for_status()
              return response.json()
          except httpx.HTTPError as e:
              return {"error": str(e)}