PDF.co MCP Server

Instructions

Convert email to PDF.
Ref: https://developer.pdf.co/api-reference/pdf-from-email.md

Implementation Reference

• pdfco/mcp/tools/apis/conversion.py:869-916 (handler)

  The primary handler for the 'email_to_pdf' MCP tool. Defines input schema with Pydantic Fields and delegates to convert_from service function.

  @mcp.tool()
  async def email_to_pdf(
      url: str = Field(
          description="URL to the source file (MSG, EML). Supports publicly accessible links including Google Drive, Dropbox, PDF.co Built-In Files Storage. Use 'upload_file' tool to upload local files."
      ),
      embedAttachments: bool = Field(
          description="Set to true to automatically embeds all attachments from original input email MSG or EML files into the final output PDF. Set it to false if you don’t want to embed attachments so it will convert only the body of the input email. True by default.",
          default=True,
      ),
      convertAttachments: bool = Field(
          description="Set to false if you don’t want to convert attachments from the original email and want to embed them as original files (as embedded PDF attachments). Converts attachments that are supported by the PDF.co API (DOC, DOCx, HTML, PNG, JPG etc.) into PDF format and then merges into output final PDF. Non-supported file types are added as PDF attachments (Adobe Reader or another viewer may be required to view PDF attachments).",
          default=True,
      ),
      margins: str = Field(
          description="Set to CSS style margins like 10px, 5mm, 5in for all sides or 5px 5px 5px 5px (the order of margins is top, right, bottom, left). (Optional)",
          default="",
      ),
      paperSize: str = Field(
          description="A4 is set by default. Can be Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 or a custom size. Custom size can be set in px (pixels), mm or in (inches) with width and height separated by space like this: 200 300, 200px 300px, 200mm 300mm, 20cm 30cm or 6in 8in. (Optional)",
          default="",
      ),
      orientation: str = Field(
          description="Set to Portrait or Landscape. Portrait is set by default. (Optional)",
          default="",
      ),
      api_key: str = Field(
          description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)",
          default="",
      ),
  ) -> BaseResponse:
      """
      Convert email to PDF.
      Ref: https://developer.pdf.co/api-reference/pdf-from-email.md
      """
      return await convert_from(
          "pdf",
          "email",
          ConversionParams(
              url=url,
              embedAttachments=embedAttachments,
              convertAttachments=convertAttachments,
              margins=margins,
              paperSize=paperSize,
              orientation=orientation,
              api_key=api_key,
          ),
      )

• pdfco/mcp/services/pdf.py:12-15 (helper)

  Helper function convert_from that builds the PDF.co API endpoint '/pdf/convert/from/email' and invokes the HTTP request.

  async def convert_from(
      _to: str, _from: str, params: ConversionParams, api_key: str | None = None
  ) -> BaseResponse:
      return await request(f"{_to}/convert/from/{_from}", params, api_key=api_key)

• pdfco/mcp/services/pdf.py:125-154 (helper)

  Core HTTP request helper that sends POST to PDF.co API v1 endpoints using PDFCoClient and returns BaseResponse.

  async def request(
      endpoint: str,
      params: ConversionParams,
      custom_payload: dict | None = None,
      api_key: str | None = None,
  ) -> BaseResponse:
      payload = params.parse_payload(async_mode=True)
      if custom_payload:
          payload.update(custom_payload)
  
      try:
          async with PDFCoClient(api_key=api_key) as client:
              url = f"/v1/{endpoint}"
              print(f"Requesting {url} with payload {payload}", file=sys.stderr)
              response = await client.post(url, json=payload)
              print(f"response: {response}", file=sys.stderr)
              json_data = response.json()
              return BaseResponse(
                  status="working",
                  content=json_data,
                  credits_used=json_data.get("credits"),
                  credits_remaining=json_data.get("remainingCredits"),
                  tips=f"You **should** use the 'wait_job_completion' tool to wait for the job [{json_data.get('jobId')}] to complete if a jobId is present.",
              )
      except Exception as e:
          return BaseResponse(
              status="error",
              content=f"{type(e)}: {[arg for arg in e.args if arg]}",
          )

• pdfco/mcp/models.py:13-160 (schema)

  Pydantic model for common conversion parameters used across tools, including parse_payload method to build API payload.

  class ConversionParams(BaseModel):
      url: str = Field(
          description="URL to the source file. Supports publicly accessible links including Google Drive, Dropbox, PDF.co Built-In Files Storage. Use 'upload_file' tool to upload local files.",
          default="",
      )
      httpusername: str = Field(
          description="HTTP auth user name if required to access source url. (Optional)",
          default="",
      )
      httppassword: str = Field(
          description="HTTP auth password if required to access source url. (Optional)",
          default="",
      )
      pages: str = Field(
          description="Comma-separated page indices (e.g., '0, 1, 2-' or '1, 3-7'). Use '!' for inverted page numbers (e.g., '!0' for last page). Processes all pages if None. (Optional)",
          default="",
      )
      unwrap: bool = Field(
          description="Unwrap lines into a single line within table cells when lineGrouping is enabled. Must be true or false. (Optional)",
          default=False,
      )
      rect: str = Field(
          description="Defines coordinates for extraction (e.g., '51.8,114.8,235.5,204.0'). (Optional)",
          default="",
      )
      lang: str = Field(
          description="Language for OCR for scanned documents. Default is 'eng'. See PDF.co docs for supported languages. (Optional, Default: 'eng')",
          default="eng",
      )
      line_grouping: str = Field(
          description="Enables line grouping within table cells when set to '1'. (Optional)",
          default="0",
      )
      password: str = Field(
          description="Password of the PDF file. (Optional)", default=""
      )
      name: str = Field(
          description="File name for the generated output. (Optional)", default=""
      )
      autosize: bool = Field(
          description="Controls automatic page sizing. If true, page dimensions adjust to content. If false, uses worksheet’s page setup. (Optional)",
          default=False,
      )
  
      html: str = Field(
          description="Input HTML code to be converted. To convert the link to a PDF use the /pdf/convert/from/url endpoint instead.",
          default="",
      )
      templateId: str = Field(
          description="Set to the ID of your HTML template. You can find and copy the ID from HTML to PDF Templates.",
          default="",
      )
      templateData: str = Field(
          description="Set it to a string with input JSON data (recommended) or CSV data.",
          default="",
      )
      margins: str = Field(
          description="Set to CSS style margins like 10px, 5mm, 5in for all sides or 5px 5px 5px 5px (the order of margins is top, right, bottom, left). (Optional)",
          default="",
      )
      paperSize: str = Field(
          description="A4 is set by default. Can be Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 or a custom size. Custom size can be set in px (pixels), mm or in (inches) with width and height separated by space like this: 200 300, 200px 300px, 200mm 300mm, 20cm 30cm or 6in 8in. (Optional)",
          default="",
      )
      orientation: str = Field(
          description="Set to Portrait or Landscape. Portrait is set by default. (Optional)",
          default="",
      )
      printBackground: bool = Field(
          description="true by default. Set to false to disable printing of background. (Optional)",
          default=True,
      )
      mediaType: str = Field(
          description="Uses print by default. Set to screen to convert HTML as it appears in a browser or print to convert as it appears for printing or none to set none as mediaType for CSS styles. (Optional)",
          default="",
      )
      DoNotWaitFullLoad: bool = Field(
          description="false by default. Set to true to skip waiting for full load (like full video load etc. that may affect the total conversion time). (Optional)",
          default=False,
      )
      header: str = Field(
          description="User definable HTML for the header to be applied on every page header. (Optional)",
          default="",
      )
      footer: str = Field(
          description="User definable HTML for the footer to be applied on every page footer. (Optional)",
          default="",
      )
  
      worksheetIndex: str = Field(
          description="Index of the worksheet to convert. (Optional)", default=""
      )
  
      def parse_payload(self, async_mode: bool = True):
          payload = {
              "async": async_mode,
          }
          if self.url:
              payload["url"] = self.url
          if self.httpusername:
              payload["httpusername"] = self.httpusername
          if self.httppassword:
              payload["httppassword"] = self.httppassword
          if self.pages:
              payload["pages"] = self.pages
          if self.unwrap:
              payload["unwrap"] = self.unwrap
          if self.rect:
              payload["rect"] = self.rect
          if self.lang:
              payload["lang"] = self.lang
          if self.line_grouping:
              payload["lineGrouping"] = self.line_grouping
          if self.password:
              payload["password"] = self.password
          if self.name:
              payload["name"] = self.name
          if self.autosize:
              payload["autosize"] = self.autosize
  
          if self.html:
              payload["html"] = self.html
          if self.templateId:
              payload["templateId"] = self.templateId
          if self.templateData:
              payload["templateData"] = self.templateData
          if self.margins:
              payload["margins"] = self.margins
          if self.paperSize:
              payload["paperSize"] = self.paperSize
          if self.orientation:
              payload["orientation"] = self.orientation
          if self.printBackground:
              payload["printBackground"] = self.printBackground
          if self.mediaType:
              payload["mediaType"] = self.mediaType
          if self.DoNotWaitFullLoad:
              payload["DoNotWaitFullLoad"] = self.DoNotWaitFullLoad
          if self.header:
              payload["header"] = self.header
          if self.footer:
              payload["footer"] = self.footer
  
          if self.worksheetIndex:
              payload["worksheetIndex"] = self.worksheetIndex
  
          return payload

• pdfco/mcp/__init__.py:3-15 (registration)

  Imports the conversion module (containing the @mcp.tool()-decorated email_to_pdf function), which registers the tool with the FastMCP instance.

  from pdfco.mcp.tools.apis import (
      conversion,
      job,
      file,
      modification,
      form,
      search,
      searchable,
      security,
      document,
      extraction,
      editing,
  )