Beehiiv MCP Server

Instructions

Retrieve a single post by ID.

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

Implementation Reference

• beehiiv_server.py:82-102 (handler)

  The main handler function for the 'get_post' tool. It is decorated with @mcp.tool() for registration, fetches post data from the Beehiiv API using the helper function, and returns a formatted string with title, subtitle, URL, status, and authors.

  @mcp.tool()
  async def get_post(publication_id: str, post_id: str) -> str:
      """
      Retrieve a single post by ID.
  
      Args:
          publication_id: ID of the publication
          post_id:        ID of the post
      """
      path = f"/publications/{publication_id}/posts/{post_id}"
      data = await beehiiv_request("GET", path)
      if not data or "data" not in data:
          return "Failed to fetch the post."
      post = data["data"]
      return (
          f"Title: {post.get('title')}\n"
          f"Subtitle: {post.get('subtitle')}\n"
          f"URL: {post.get('web_url')}\n"
          f"Status: {post.get('status')}\n"
          f"Authors: {post.get('authors')}"
      )

• beehiiv_server.py:17-50 (helper)

  Supporting utility function 'beehiiv_request' used by the get_post handler to make authenticated HTTP requests to the Beehiiv API.

  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:82-82 (registration)

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

  @mcp.tool()