Beehiiv MCP Server

Instructions

Create a new post using provided HTML content.

Args:
    publication_id: ID of the publication
    title: Title of the new post
    subtitle: Subtitle of the new post
    html_content: HTML content for the post

Implementation Reference

• beehiiv_server.py:137-173 (handler)

  The core handler function for the 'create_new_post' MCP tool. It is registered via @mcp.tool() decorator and implements the logic to create a new post in Beehiiv by posting title, subtitle, and HTML content to the API endpoint.

  @mcp.tool()
  # have not tested this as I am not an enterprise customer, but leaving here for reference
  async def create_new_post(publication_id: str, title: str, subtitle: str, html_content: str) -> str:
      """
      Create a new post using provided HTML content.
  
      Args:
          publication_id: ID of the publication
          title: Title of the new post
          subtitle: Subtitle of the new post
          html_content: HTML content for the post
      """
      path = f"/publications/{publication_id}/posts"
      
      post_data = {
          "title": title,
          "subtitle": subtitle,
          "content": {
              "free": {
                  "web": html_content,
                  "email": html_content,  # You might want to format this differently for email
                  "rss": html_content    # And for RSS
              }
          }
      }
      
      response = await beehiiv_request("POST", path, json_body=post_data)
      
      if not response or "data" not in response:
          return f"Failed to create post: {response.get('error', 'Unknown error')}"
      
      new_post = response["data"]
      return {
          "status": "success",
          "post_id": new_post.get("id"),
          "web_url": new_post.get("web_url")
      }

• beehiiv_server.py:17-50 (helper)

  Supporting helper function 'beehiiv_request' used by the create_new_post handler to make authenticated API calls 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)}

• beehiiv_server.py:137-137 (registration)

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

  @mcp.tool()