{"id":45398155,"url":"https://github.com/NimbleBrainInc/mcp-pdfco","last_synced_at":"2026-03-06T20:01:35.758Z","repository":{"id":318919045,"uuid":"1073134779","full_name":"NimbleBrainInc/mcp-pdfco","owner":"NimbleBrainInc","description":"PDFCo MCP Server","archived":false,"fork":false,"pushed_at":"2026-02-14T02:49:59.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T09:22:59.043Z","etag":null,"topics":["mcp","mcpb","nimblebrain","nimbletools","pdfco"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NimbleBrainInc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T17:04:16.000Z","updated_at":"2026-02-14T02:50:02.000Z","dependencies_parsed_at":"2025-10-17T07:09:53.086Z","dependency_job_id":"d8f1f616-a450-4876-b352-6a66f3a0c2ea","html_url":"https://github.com/NimbleBrainInc/mcp-pdfco","commit_stats":null,"previous_names":["nimblebraininc/mcp-pdfco"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/NimbleBrainInc/mcp-pdfco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-pdfco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-pdfco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-pdfco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-pdfco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NimbleBrainInc","download_url":"https://codeload.github.com/NimbleBrainInc/mcp-pdfco/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-pdfco/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30195529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcpb","nimblebrain","nimbletools","pdfco"],"created_at":"2026-02-21T19:44:50.174Z","updated_at":"2026-03-06T20:01:35.749Z","avatar_url":"https://github.com/NimbleBrainInc.png","language":"Python","funding_links":[],"categories":["Utilities"],"sub_categories":[],"readme":"# MCP Server PDF.co\n\n[![NimbleTools Registry](https://img.shields.io/badge/NimbleTools-Registry-green)](https://github.com/nimbletoolsinc/mcp-registry)\n[![NimbleBrain Platform](https://img.shields.io/badge/NimbleBrain-Platform-blue)](https://www.nimblebrain.ai)\n[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord\u0026logoColor=white)](https://www.nimblebrain.ai/discord?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=mcp-pdfco\u0026utm_content=discord-badge)\n\n\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/NimbleBrainInc/mcp-pdfco/actions/workflows/ci.yaml/badge.svg)](https://github.com/NimbleBrainInc/mcp-pdfco/actions)\n\n## About\n\nMCP server for PDF.co API. Comprehensive PDF manipulation, conversion, OCR,\ntext extraction, and document automation with support for barcodes,\nwatermarks, and security features.\n\n## Features\n\n- **Full API Coverage**: Complete implementation of PDF.co API endpoints\n- **Strongly Typed**: All responses use Pydantic models for type safety\n- **S-Tier Architecture**: Production-ready with separated concerns (API client, models, server)\n- **HTTP Transport**: Supports streamable-http with health endpoint\n- **Async/Await**: Built on aiohttp for high performance\n- **Type Safe**: Full mypy strict mode compliance\n- **Comprehensive Testing**: Unit tests with pytest and AsyncMock\n- **Docker Ready**: Production Dockerfile included\n- **Built-in Skill Resource**: Serves a `skill://pdfco/usage` resource that teaches LLMs HTML best practices, tool selection, and error recovery\n\n## Available Tools\n\n### PDF Conversion Tools\n\n- `pdf_to_text` - Extract text content from PDF documents\n- `pdf_to_json` - Extract structured data from PDFs\n- `pdf_to_html` - Convert PDF to HTML format\n- `pdf_to_csv` - Extract tables from PDF to CSV\n\n### PDF Manipulation Tools\n\n- `pdf_merge` - Combine multiple PDFs into one\n- `pdf_split` - Split PDF into separate pages or ranges\n- `pdf_rotate` - Rotate pages in a PDF document\n- `pdf_compress` - Reduce PDF file size with configurable compression\n- `pdf_add_watermark` - Add text watermarks to PDFs\n\n### PDF Security Tools\n\n- `pdf_protect` - Add password protection to PDFs\n- `pdf_unlock` - Remove password protection from PDFs\n\n### PDF Information\n\n- `pdf_info` - Get PDF metadata (pages, size, dimensions, etc.)\n\n### Document Creation Tools\n\n- `html_to_pdf` - Convert HTML content to PDF\n- `url_to_pdf` - Convert web pages to PDF\n- `image_to_pdf` - Convert images to PDF documents\n\n### Barcode Tools\n\n- `barcode_generate` - Generate QR codes and barcodes\n- `barcode_read` - Read and decode barcodes from images\n\n### OCR Tools\n\n- `ocr_pdf` - OCR scanned PDFs to make them searchable\n\n## Installation\n\n### Using uv (recommended)\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd mcp-pdfco\n\n# Install with uv\nuv pip install -e .\n\n# Install with development dependencies\nuv pip install -e \".[dev]\"\n```\n\n### Using pip\n\n```bash\npip install -e .\n```\n\n## Configuration\n\n### API Key\n\nGet your free API key from [PDF.co Dashboard](https://app.pdf.co/dashboard) and set it as an environment variable:\n\n```bash\nexport PDFCO_API_KEY=your_api_key_here\n```\n\nOr create a `.env` file:\n\n```env\nPDFCO_API_KEY=your_api_key_here\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop configuration file:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pdfco\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-pdfco\"],\n      \"env\": {\n        \"PDFCO_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n## Running the Server\n\n### Development Mode\n\n```bash\n# Using Python module\nuv run python -m mcp_pdfco.server\n\n# Using the Makefile\nmake run\n```\n\n### Production Mode (Docker)\n\n```bash\n# Build the Docker image\ndocker build -t mcp-pdfco .\n\n# Run with Docker\ndocker run -e PDFCO_API_KEY=your_key -p 8000:8000 mcp-pdfco\n\n# Run with Docker Compose\ndocker-compose up\n```\n\n### HTTP Transport\n\nThe server supports HTTP transport with a health check endpoint:\n\n```bash\n# Start with uvicorn\nuvicorn mcp_pdfco.server:app --host 0.0.0.0 --port 8000\n\n# Check health\ncurl http://localhost:8000/health\n```\n\n## Usage Examples\n\n### Extract Text from PDF\n\n```python\nresult = await pdf_to_text(\n    url=\"https://example.com/document.pdf\",\n    pages=\"1-5\"\n)\nprint(result.text)\n```\n\n### Merge Multiple PDFs\n\n```python\nresult = await pdf_merge(\n    urls=[\n        \"https://example.com/doc1.pdf\",\n        \"https://example.com/doc2.pdf\"\n    ],\n    name=\"merged_document.pdf\"\n)\nprint(f\"Merged PDF: {result.url}\")\n```\n\n### Convert HTML to PDF\n\n```python\nresult = await html_to_pdf(\n    html=\"\u003ch1\u003eHello World\u003c/h1\u003e\u003cp\u003eThis is a PDF\u003c/p\u003e\",\n    name=\"hello.pdf\",\n    page_size=\"A4\",\n    orientation=\"Portrait\"\n)\nprint(f\"Generated PDF: {result.url}\")\n```\n\n### Add Watermark\n\n```python\nresult = await pdf_add_watermark(\n    url=\"https://example.com/document.pdf\",\n    text=\"CONFIDENTIAL\",\n    x=200,\n    y=400,\n    font_size=48,\n    color=\"FF0000\",\n    opacity=0.3,\n    pages=\"0-\",  # Apply to all pages\n    name=\"watermarked_document.pdf\"\n)\nprint(f\"Watermarked PDF: {result.url}\")\n```\n\n### Generate QR Code\n\n```python\nresult = await barcode_generate(\n    value=\"https://example.com\",\n    barcode_type=\"QRCode\",\n    format=\"png\"\n)\nprint(f\"QR Code: {result.url}\")\n```\n\n### OCR a Scanned PDF\n\n```python\nresult = await ocr_pdf(\n    url=\"https://example.com/scanned.pdf\",\n    pages=\"1-10\",\n    lang=\"eng\"\n)\nprint(f\"OCR'd PDF: {result.url}\")\nprint(f\"Extracted text: {result.text}\")\n```\n\n## Development\n\n### Quick Start\n\n```bash\nmake help          # Show all available commands\nmake install       # Install dependencies\nmake dev-install   # Install with dev dependencies\nmake format        # Format code with ruff\nmake lint          # Lint code with ruff\nmake typecheck     # Type check with mypy\nmake test          # Run tests with pytest\nmake test-cov      # Run tests with coverage\nmake check         # Run all checks (lint + typecheck + test)\nmake clean         # Clean up artifacts\n```\n\n### Project Structure\n\n```\n.\n├── src/\n│   └── mcp_pdfco/\n│       ├── __init__.py\n│       ├── server.py          # FastMCP server with tool definitions\n│       ├── api_client.py      # Async PDF.co API client\n│       └── api_models.py      # Pydantic models for type safety\n├── tests/\n│   ├── __init__.py\n│   ├── test_server.py         # Server tool tests\n│   └── test_api_client.py     # API client tests\n├── pyproject.toml             # Project configuration\n├── Makefile                   # Development commands\n├── Dockerfile                 # Container deployment\n└── README.md                  # This file\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src/mcp_pdfco --cov-report=term-missing\n\n# Run specific test file\npytest tests/test_server.py -v\n```\n\n### Code Quality\n\nThis project uses:\n- **ruff**: Fast Python linter and formatter\n- **mypy**: Static type checker (strict mode)\n- **pytest**: Testing framework with async support\n\nAll code must pass:\n```bash\nmake check  # Runs lint + typecheck + test\n```\n\n## Architecture\n\nThis server follows S-Tier MCP architecture principles:\n\n1. **Separation of Concerns**\n   - `api_client.py`: HTTP communication layer\n   - `api_models.py`: Data models and type definitions\n   - `server.py`: MCP tool definitions and routing\n\n2. **Type Safety**\n   - Full type hints on all functions\n   - Pydantic models for API responses\n   - Mypy strict mode compliance\n\n3. **Async All the Way**\n   - aiohttp for HTTP requests\n   - Async/await throughout\n   - Context managers for resource cleanup\n\n4. **Error Handling**\n   - Custom `PDFcoAPIError` exception\n   - Context logging via `ctx.error()` and `ctx.warning()`\n   - Graceful error messages\n\n5. **Production Ready**\n   - Docker support\n   - Health check endpoint\n   - Environment-based configuration\n   - Comprehensive logging\n\n## Requirements\n\n- Python 3.13+\n- aiohttp \u003e= 3.12.15\n- fastmcp \u003e= 2.14.0\n- pydantic \u003e= 2.0.0\n\n## API Documentation\n\nFor detailed API documentation, visit [PDF.co API Documentation](https://apidocs.pdf.co/).\n\n### Supported Input Formats\n\n- **PDF**: URL or base64 encoded\n- **Images**: PNG, JPG, GIF, BMP, TIFF\n- **HTML**: Raw HTML string or URL\n\n### Supported Output Formats\n\n- **PDF**: High-quality PDF generation\n- **Text**: Plain text extraction\n- **JSON**: Structured data extraction\n- **HTML**: Formatted HTML output\n- **CSV**: Table data extraction\n- **Images**: PNG, JPG, SVG for barcodes\n\n### Rate Limits\n\nPDF.co has rate limits based on your subscription plan. Free plans include:\n- 100 API calls per month\n- 10 API calls per minute\n\nCheck your [dashboard](https://app.pdf.co/dashboard) for current usage.\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue**: `PDFCO_API_KEY is not set` warning\n\n**Solution**: Set the environment variable:\n```bash\nexport PDFCO_API_KEY=your_key_here\n```\n\n**Issue**: `Network error` or timeout\n\n**Solution**: Check your internet connection and increase timeout:\n```python\nclient = PDFcoClient(timeout=180.0)  # 3 minutes\n```\n\n**Issue**: `API Error 401: Unauthorized`\n\n**Solution**: Verify your API key is valid at https://app.pdf.co/dashboard\n\n**Issue**: Docker container won't start\n\n**Solution**: Ensure the API key is passed correctly:\n```bash\ndocker run -e PDFCO_API_KEY=your_key_here -p 8000:8000 mcp-pdfco\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `make check`\n5. Submit a pull request\n\nIssue Tracker: [GitHub Issues](https://github.com/your-org/mcp-pdfco/issues)\n\n## License\n\nMIT\n\n## Links\n\nPart of the [NimbleTools Registry](https://github.com/nimbletoolsinc/mcp-registry) - an open source collection of production-ready MCP servers. For enterprise deployment, check out [NimbleBrain](https://www.nimblebrain.ai).\n\n### API Documentation\n\n- [PDF.co Documentation](https://apidocs.pdf.co/)\n- [PDF Operations](https://apidocs.pdf.co/02-pdf-to-text)\n- [Conversion APIs](https://apidocs.pdf.co/07-html-to-pdf)\n- [OCR API](https://apidocs.pdf.co/12-pdf-ocr)\n- [Barcode API](https://apidocs.pdf.co/24-barcode-generate)\n\n### Support\n\n- [Help Center](https://pdf.co/support)\n- [API Documentation](https://apidocs.pdf.co/)\n- [Contact Support](https://pdf.co/contact)\n- [Status Page](https://status.pdf.co/)\n- Built with [FastMCP](https://github.com/jlowin/fastmcp)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-pdfco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNimbleBrainInc%2Fmcp-pdfco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-pdfco/lists"}