pdf_add_annotations_images_fields
Add text annotations, images, and fill form fields in PDF and scanned PDF files. Update PDFs with comments, logos, or completed forms.
Instructions
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.mdInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | 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 | No | HTTP auth user name if required to access source url. (Optional) | |
| httppassword | No | HTTP auth password if required to access source url. (Optional) | |
| password | No | Password for the PDF file. (Optional) | |
| name | No | File name for the generated output. (Optional) | |
| annotations | No | 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) | |
| images | No | 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) | |
| fields | No | 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) | |
| expiration | No | Set the expiration time for the output link in minutes. After this specified duration, any generated output file(s) will be automatically deleted. (Optional) | |
| encrypt | No | Encrypt output file. (Optional) | |
| flatten | No | Flatten filled form fields and annotations into PDF content. Set to true to disable editing of filled form fields in the output PDF. (Optional) | |
| api_key | No | PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional) |
Implementation Reference
- pdfco/mcp/tools/apis/editing.py:10-102 (handler)The main handler function for the 'pdf_add_annotations_images_fields' tool. It is decorated with @mcp.tool(), accepts parameters for annotations, images, fields, plus common PDF processing parameters, and delegates to the pdf_add service function.
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) - Input schema/validation for the tool defined via Pydantic Field() annotations on each parameter (url, httpusername, httppassword, password, name, annotations, images, fields, expiration, encrypt, flatten, api_key).
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="", ), - pdfco/mcp/services/pdf.py:48-61 (helper)The pdf_add helper function that constructs the custom payload from kwargs and makes the API request to 'pdf/edit/add' endpoint.
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 ) - pdfco/mcp/tools/apis/editing.py:9-10 (registration)The @mcp.tool() decorator registers this function as an MCP tool named 'pdf_add_annotations_images_fields'.
@mcp.tool() async def pdf_add_annotations_images_fields(