{"id":5362,"library":"pdf-tools-mcp","title":"PDF Tools MCP Server","description":"pdf-tools-mcp is a FastAPI-based server for reading and manipulating PDF documents. It provides a RESTful API for common PDF operations like splitting, merging, extracting pages, adding content, watermarking, converting, compression, and OCR. The current version is 0.1.4, and its release cadence is irregular, driven by feature additions and maintenance.","status":"active","version":"0.1.4","language":"en","source_language":"en","source_url":"https://github.com/lockon-n/pdf-tools-mcp","tags":["pdf","fastapi","rest-api","document-processing","ocr","pypdf"],"install":[{"cmd":"pip install pdf-tools-mcp","lang":"bash","label":"Install core package"},{"cmd":"pip install pdf-tools-mcp[ocr,weasyprint,reportlab]","lang":"bash","label":"Install with optional dependencies"}],"dependencies":[{"reason":"Core web framework for the server.","package":"fastapi"},{"reason":"ASGI server for running the FastAPI application.","package":"uvicorn"},{"reason":"Primary library for PDF manipulation.","package":"pypdf"},{"reason":"Image processing for adding content or converting.","package":"Pillow"},{"reason":"Required for OCR functionality.","package":"opencv-python-headless","optional":true},{"reason":"Required for OCR functionality.","package":"pytesseract","optional":true},{"reason":"Required for HTML to PDF conversion.","package":"weasyprint","optional":true},{"reason":"Required for PDF generation features.","package":"reportlab","optional":true}],"imports":[{"note":"While this imports the FastAPI app instance, the primary way to use pdf-tools-mcp is by running it as a server via `python -m pdf_tools_mcp.main`, not by importing its components for direct library use. This import is mainly for programmatic setup or testing.","symbol":"app","correct":"from pdf_tools_mcp.main import app"}],"quickstart":{"code":"# 1. Install the library\npip install pdf-tools-mcp\n\n# 2. Run the PDF tools server\n# In your terminal, run:\n# python -m pdf_tools_mcp.main\n\n# 3. Access the API (e.g., using curl in another terminal)\n# curl http://127.0.0.1:8000/api/v1/health\n\n# Expected output for health check (after server starts):\n# {\"status\":\"ok\"}\n\n# Example Python client interaction (requires 'requests')\nimport requests\n\nBASE_URL = \"http://127.0.0.1:8000/api/v1\"\n\ntry:\n    response = requests.get(f\"{BASE_URL}/health\")\n    response.raise_for_status() # Raise an exception for HTTP errors\n    print(f\"Health check: {response.json()}\")\n\n    # Example: Upload a PDF (assuming you have 'example.pdf' locally)\n    # with open('example.pdf', 'rb') as f:\n    #     files = {'file': ('example.pdf', f, 'application/pdf')}\n    #     upload_response = requests.post(f\"{BASE_URL}/pdf/split\", files=files,\n    #                                     params={'pages': '1'})\n    #     upload_response.raise_for_status()\n    #     print(f\"Upload/Split response: {upload_response.json()}\")\n\nexcept requests.exceptions.ConnectionError:\n    print(\"Error: Could not connect to the pdf-tools-mcp server. Is it running?\")\nexcept requests.exceptions.RequestException as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to install and run the `pdf-tools-mcp` server, and how to perform a basic health check using `curl` or a Python `requests` client. Remember to run the `python -m pdf_tools_mcp.main` command in a separate terminal to start the server before making API requests. The server typically runs on `http://127.0.0.1:8000` by default."},"warnings":[{"fix":"Run the server using `python -m pdf_tools_mcp.main` and interact with it via HTTP requests (e.g., using `requests` in Python or `curl`).","message":"pdf-tools-mcp is primarily designed as a standalone FastAPI server, not a Python library for direct function calls. Its core functionality is exposed via HTTP endpoints. Attempting to import and use internal modules directly without running the server might lead to unexpected behavior or incomplete functionality.","severity":"gotcha","affected_versions":"0.1.0+"},{"fix":"Install the package with the required extras: `pip install pdf-tools-mcp[ocr,weasyprint,reportlab]` for full functionality. Check the `pyproject.toml` or `README` for specific feature-to-extra mappings.","message":"Several advanced features like OCR, HTML to PDF conversion, and advanced PDF generation depend on optional 'extras' dependencies. If you don't install these, the corresponding API endpoints or features will not work and might return HTTP 500 errors or validation failures.","severity":"gotcha","affected_versions":"0.1.0+"},{"fix":"Ensure your Python environment is version 3.12 or higher. Consider using `pyenv` or `conda` to manage multiple Python versions if needed.","message":"The library explicitly requires Python 3.12 or newer. Running it with older Python versions (e.g., 3.11 or 3.10) will result in installation failures or runtime errors due to syntax or dependency incompatibilities.","severity":"breaking","affected_versions":"0.1.0+"},{"fix":"Refer to FastAPI's documentation on `UploadFile` and `requests` library documentation on file uploads for correct client-side implementation. Example: `files = {'file': ('my_document.pdf', open('my_document.pdf', 'rb'), 'application/pdf')}`.","message":"When interacting with file upload endpoints (e.g., for splitting or merging PDFs), ensure you correctly format your `multipart/form-data` request. For Python's `requests` library, use the `files` parameter with a tuple `('filename', file_object, 'content_type')`.","severity":"gotcha","affected_versions":"0.1.0+"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}