pdf-agent-kit

pdf-agent-kit is a local adapter package for the pdf-agent-kit cloud API.

• MCP entrypoint: pdf-agent-kit (stdio, one tool: extract_pdf_to_json)
• CLI entrypoint: pdf-edit
• Python import: from pdf_agent_kit import extract

The package is thin by design: it reads a local PDF file and forwards it to the cloud API. If PDF_EDITOR_API_KEY is present, it uses your paid account. If not, it auto-creates a guest session with free credits.

Quickstart For Agents

from pdf_agent_kit import extract

result = extract("/absolute/path/to/file.pdf", pages="1-3")

Install

pip install pdf-agent-kit

or:

uvx pdf-agent-kit

Python Compatibility

• CLI (pdf-edit) works on Python 3.9+.
• MCP server (pdf-agent-kit) requires Python 3.10+ because fastmcp is only installed on 3.10+.
• If your agent is pinned to older Python, use pdf-edit directly or use uvx pdf-agent-kit for MCP runtime.

Auth Modes

export PDF_EDITOR_API_KEY="sk_live_..."

If no key is set, pdf-agent-kit uses guest mode automatically.

You can also persist your API key locally (avoids exporting every session):

pdf-edit setup --save-api-key

When guest credits run out, the CLI/MCP response points users to pdfagentkit.com/dashboard to register and continue.

MCP Tool

Tool name: extract_pdf_to_json

Parameters:

• file_path (required)
• pages (optional, default all)
• filename (optional override)

Returns API JSON: metadata + per-page text + usage stats.

CLI

pdf-edit extract /path/to/file.pdf
pdf-edit extract /path/to/file.pdf --pages "1-5"
pdf-edit extract /path/to/file.pdf -o /path/to/output.json
pdf-edit status
pdf-edit setup --save-api-key

CLI contract:

• success JSON goes to stdout
• errors go to stderr
• exit code 0 success, 1 user error, 2 server/network error
• extract prints a concise usage summary to stderr (pages + remaining credits)

Setup

pdf-edit setup:

1. Reads PDF_EDITOR_API_KEY (or prompts once if missing)
2. Verifies key with /v1/account/status
3. Patches MCP config for:
   • Claude Desktop
   • Cursor
   • VS Code
4. Tries to add Claude Code integration via claude mcp add-json
5. Optionally saves API key to ~/.pdf-agent-kit/config.json with --save-api-key

Injected server entry:

{
  "mcpServers": {
    "pdf-agent-kit": {
      "command": "uvx",
      "args": ["pdf-agent-kit"],
      "env": {
        "PDF_EDITOR_API_KEY": "sk_live_..."
      }
    }
  }
}

Development

pip install -e .[dev]
pytest -q