PDF.co MCP Server

Instructions

Implementation Reference

• pdfco/mcp/tools/apis/editing.py:9-103 (handler)

  The handler function for the tool 'pdf_add_annotations_images_fields'. It is decorated with @mcp.tool() for registration and defines the input schema using Pydantic Field descriptions. The logic prepares parameters and calls the pdf_add helper to perform the PDF editing via API.
  @mcp.tool() async def pdf_add_annotations_images_fields( url: str = Field( description="URL to the source PDF file. Supports publicly accessible links including Google Drive, Dropbox, PDF.co Built-In Files Storage. Use 'upload_file' tool to upload local files." ), 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="", ), password: str = Field( description="Password for the PDF file. (Optional)", default="" ), name: str = Field( description="File name for the generated output. (Optional)", default="" ), annotations: List[Any] = Field( description="Array of annotation objects to add text, links, shapes, etc. Each object can have: 'text' (string), 'x' (number), 'y' (number), 'size' (number), 'pages' (string), 'color' (string hex), 'link' (string URL), 'fontName' (string), 'fontItalic' (boolean), 'fontBold' (boolean), 'fontStrikeout' (boolean), 'fontUnderline' (boolean). (Optional)", default=[], ), images: List[Any] = Field( description="Array of image objects to add images to PDF. Each object can have: 'url' (string), 'x' (number), 'y' (number), 'width' (number), 'height' (number), 'pages' (string). (Optional)", default=[], ), fields: List[Any] = Field( description="Array of form field objects to fill PDF form fields. Each object can have: 'fieldName' (string), 'pages' (string), 'text' (string), 'fontName' (string), 'size' (number), 'fontBold' (boolean), 'fontItalic' (boolean), 'fontStrikeout' (boolean), 'fontUnderline' (boolean). (Optional)", default=[], ), expiration: int = Field( description="Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted. (Optional)", default=60, ), encrypt: bool = Field(description="Encrypt output file. (Optional)", default=False), flatten: bool = Field( description="Flatten filled form fields and annotations into PDF content. Set to true to disable editing of filled form fields in the output PDF. (Optional)", default=False, ), api_key: str = Field( description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)", default="", ), ) -> BaseResponse: """ Add text, images, forms, other PDFs, fill forms, links to external sites and external PDF files. You can update or modify PDF and scanned PDF files. This tool supports three main ways to add content: 1. **annotations**: Add text, links, shapes, etc. Properties: text, x, y, size, pages, color, link, fontName, fontItalic, fontBold, fontStrikeout, fontUnderline 2. **images**: Add images or other PDF content Properties: url, x, y, width, height, pages 3. **fields**: Fill existing form fields Properties: fieldName, pages, text, fontName, size, fontBold, fontItalic, fontStrikeout, fontUnderline Example annotations: [{"text": "Sample Text - Click here to test link", "x": 250, "y": 240, "size": 24, "pages": "0-", "color": "CCBBAA", "link": "https://pdf.co/", "fontName": "Comic Sans MS", "fontItalic": true, "fontBold": true, "fontStrikeout": false, "fontUnderline": true}] Example images: [{"url": "https://pdfco-test-files.s3.us-west-2.amazonaws.com/pdf-edit/logo.png", "x": 270, "y": 150, "width": 159, "height": 43, "pages": "0"}] Example fields: [{"fieldName": "topmostSubform[0].Page1[0].YourSocial_ReadOrderControl[0].f1_05[0]", "pages": "1", "text": "Joan B.", "fontName": "Arial", "size": 6, "fontBold": true, "fontItalic": true, "fontStrikeout": true, "fontUnderline": true}] Ref: https://developer.pdf.co/api-reference/pdf-add.md """ params = ConversionParams( url=url, httpusername=httpusername, httppassword=httppassword, password=password, name=name, expiration=expiration, ) # Prepare additional parameters add_params = {} if annotations: add_params["annotations"] = annotations if images: add_params["images"] = images if fields: add_params["fields"] = fields if encrypt: add_params["encrypt"] = encrypt if flatten: add_params["flatten"] = flatten return await pdf_add(params, **add_params, api_key=api_key)
• pdfco/mcp/services/pdf.py:48-61 (helper)

  Supporting helper function pdf_add that constructs the API request to 'pdf/edit/add' endpoint, passing annotations, images, fields etc. as custom payload to the PDF.co API.
  async def pdf_add( params: ConversionParams, api_key: str | None = None, **kwargs ) -> BaseResponse: """General PDF Add function that supports all PDF Add API parameters""" custom_payload = {} # Add all supported parameters for key, value in kwargs.items(): if value is not None and value != "": custom_payload[key] = value return await request( "pdf/edit/add", params, custom_payload=custom_payload, api_key=api_key )