PDF Manipulation MCP Server

Instructions

Implementation Reference

• pdf_manipulation_mcp_server/pdf_server.py:42-92 (handler)

  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)}"

• pdf_manipulation_mcp_server/pdf_server.py:22-26 (helper)

  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}")

• pdf_manipulation_mcp_server/pdf_server.py:28-35 (helper)

  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

• pdf_manipulation_mcp_server/pdf_server.py:37-39 (helper)

  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()