Metadata-Version: 2.4
Name: oxpdf-mcp
Version: 0.1.0
Summary: MCP server for 0xPdf — schema-first PDF to structured JSON for AI agents
License-Expression: MIT
Project-URL: Homepage, https://0xpdf.io
Project-URL: Documentation, https://0xpdf.io/docs#mcp
Project-URL: Playground, https://0xpdf.io/samples
Project-URL: Repository, https://github.com/risha-max/0xpdf-mcp
Project-URL: Issues, https://github.com/risha-max/0xpdf-mcp/issues
Keywords: mcp,pdf,ocr,json,schema,0xpdf,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.27.0
Dynamic: license-file

# 0xPdf MCP

[![PyPI](https://img.shields.io/pypi/v/oxpdf-mcp)](https://pypi.org/project/oxpdf-mcp/)
[![MCP](https://img.shields.io/badge/MCP-stdio-blue)](https://modelcontextprotocol.io/)

**Schema in → PDF in → JSON out** for Claude, Cursor, and other MCP clients.

This stdio MCP server wraps the [0xPdf](https://0xpdf.io) HTTP API (auth, billing, rate limits intact). Agents can parse invoices/forms into a JSON schema, generate schemas, and poll async jobs.

![0xPdf — schema in, PDF in, JSON out](https://0xpdf.io/media/social-promo.gif)

[Playground](https://0xpdf.io/samples?utm_source=github&utm_medium=readme&utm_campaign=0xpdf-mcp) · [Docs / MCP setup](https://0xpdf.io/docs#mcp) · [Pricing](https://0xpdf.io/pricing)

## Install

```bash
pip install oxpdf-mcp
# or
uvx oxpdf-mcp
```

Get an API key at [0xpdf.io/dashboard](https://0xpdf.io/dashboard).

## Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "0xpdf": {
      "command": "uvx",
      "args": ["oxpdf-mcp"],
      "env": {
        "PDF_PARSING_API_BASE_URL": "https://api.0xpdf.io",
        "PDF_PARSING_API_PREFIX": "api/v1",
        "PDF_PARSING_API_KEY": "YOUR_API_KEY",
        "PDF_PARSING_ALLOWED_API_HOSTS": "api.0xpdf.io",
        "PDF_PARSING_REQUIRE_HTTPS": "true",
        "PDF_PARSING_ALLOWED_FILE_ROOTS": "/home/YOU/Downloads:/home/YOU/Documents",
        "PDF_PARSING_MCP_DISALLOW_FULL_RESPONSE_MODE": "true"
      }
    }
  }
}
```

Or with pip:

```json
"command": "oxpdf-mcp"
```

## Tools (selected)

| Tool | Purpose |
|------|---------|
| `parse_pdf_sync` | Schema-first sync parse |
| `parse_pdf_stream` | Streaming parse (SSE) |
| `submit_parse_job` / `wait_for_job_completion` | Async jobs |
| `list_schemas` / `create_schema` | Saved schemas |
| `generate_schema_from_description` | AI schema generation (wallet debit) |
| `get_pricing_current` | Balance / pricing |
| `health_check` | Liveness |

Full list and env vars: see source `oxpdf_mcp/server.py` and [docs](https://0xpdf.io/docs#mcp).

## Env

| Variable | Default | Notes |
|----------|---------|--------|
| `PDF_PARSING_API_KEY` | — | Required for authenticated tools |
| `PDF_PARSING_API_BASE_URL` | `https://api.0xpdf.io` | Production API |
| `PDF_PARSING_ALLOWED_API_HOSTS` | — | Required in production (`api.0xpdf.io`) |
| `PDF_PARSING_REQUIRE_HTTPS` | `false` | Set `true` for production |
| `PDF_PARSING_ALLOWED_FILE_ROOTS` | CWD | Colon-separated absolute paths for `pdf_path` |

## SDKs (non-MCP)

- Python: [`oxpdf`](https://pypi.org/project/oxpdf/)
- JS/TS: [`@0xpdf/client`](https://www.npmjs.com/package/@0xpdf/client)

## License

MIT
