pdf_add_text
Insert custom text at precise coordinates on PDF pages to annotate documents, add labels, or include additional information.
Instructions
Add text to a PDF at a specified position.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pdf_path | Yes | ||
| page_number | Yes | ||
| text | Yes | ||
| x | Yes | ||
| y | Yes | ||
| font_size | No | ||
| color | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The core handler function for the 'pdf_add_text' tool. It adds text to a specified page and position in a PDF using PyMuPDF (fitz), generates a timestamped output file, and returns success/error message.
@mcp.tool() async def pdf_add_text( pdf_path: str, page_number: int, text: str, x: float, y: float, font_size: int = 12, color: List[float] = None ) -> str: """Add text to a PDF at a specified position.""" if color is None: color = [0, 0, 0] if not os.path.exists(pdf_path): return f"Error: PDF file not found: {pdf_path}" if not validate_pdf_file(pdf_path): return f"Error: Invalid PDF file: {pdf_path}" try: # Open PDF document doc = fitz.open(pdf_path) # Validate page number if not validate_page_number(doc, page_number): doc.close() return f"Error: Invalid page number {page_number}. Document has {len(doc)} pages." # Get the page page = doc[page_number] # Add text to the page page.insert_text( (x, y), text, fontsize=font_size, color=color ) # Generate output filename output_path = generate_output_filename(pdf_path) # Save the modified PDF doc.save(output_path) doc.close() return f"Successfully added text to PDF. Output saved to: {output_path}" except Exception as e: return f"Error adding text to PDF: {str(e)}" - Utility function used by pdf_add_text to generate timestamped output filenames preventing overwrite of originals.
def generate_output_filename(input_path: str, suffix: str = "modified") -> str: """Generate a new filename with timestamp to avoid overwriting originals.""" path = Path(input_path) timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") return str(path.parent / f"{path.stem}_{suffix}_{timestamp}{path.suffix}") - Helper function used by pdf_add_text to validate the input PDF file.
def validate_pdf_file(pdf_path: str) -> bool: """Validate that the file is a valid PDF.""" try: doc = fitz.open(pdf_path) doc.close() return True except Exception: return False - Helper function used by pdf_add_text to validate the page number.
def validate_page_number(doc: fitz.Document, page_num: int) -> bool: """Validate that the page number exists in the document.""" return 0 <= page_num < len(doc) - pdf_manipulation_mcp_server/server.py:12-14 (registration)The server entry point that imports and runs the MCP server instance with all registered tools including pdf_add_text.
def main(): """Main function to run the MCP server.""" mcp.run()