# 1pdf MCP Server

**97 PDF tools for Claude, Cursor & Codex.**

Give your AI assistant the power to merge, split, compress, convert, encrypt,
add visible signatures, watermark, and analyze PDFs — all with natural
language. Core tools run locally; professional document conversions can use
optional local programs.

Official guide: [1pdf.best/mcp](https://1pdf.best/mcp)

## Quick Start

### OpenAI Codex

```bash
codex mcp add 1pdf -- npx -y onepdf-mcp-server
```

Verify with `codex mcp list`, restart Codex, then ask:

```text
Use 1PDF to merge report1.pdf and report2.pdf.
```

### Claude Code

```bash
claude mcp add 1pdf -- npx -y onepdf-mcp-server
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "1pdf": {
      "command": "npx",
      "args": ["-y", "onepdf-mcp-server"]
    }
  }
}
```

### Cursor

Settings → MCP → Add Server:

```
Command: npx
Args: -y, onepdf-mcp-server
```

### Windsurf

Settings → MCP → Add Server:

```
npx -y onepdf-mcp-server
```

## Check Available Capabilities

Ask your Agent to call `system_status` before workflows that use Office,
MOBI, DjVu, XPS, Ghostscript, or PDF/A conversion.

The status response reports:

- the 1PDF MCP and Node versions;
- detected optional programs and versions;
- tools enabled by each program;
- platform-specific installation instructions for missing programs.

Core PDF tools run with the npm package. Professional document conversion
uses optional local programs. Missing dependencies return
`MISSING_DEPENDENCY`; 1PDF does not report a successful conversion when a
required program is missing.

## Capability Boundaries

- `sign_pdf` adds a visible signature appearance. It does not provide
  certificate-backed authenticity.
- `pdf_to_pdfa` and `font_to_outline` require Ghostscript. PDF/A conversion can
  optionally require independent veraPDF validation with `validate: true`.
- `ocg_manager` accurately lists Optional Content Groups. Persisting layer
  visibility is not available yet and returns a structured failure without
  writing a copied output.
- `deskew_pdf` automatically detects and corrects page tilt locally. The
  corrected output is rasterized, so selectable text and vector elements become
  images; use OCR afterward when searchable text is required.
- `compress` uses a lossless structural rewrite at high quality, Ghostscript
  image resampling at low quality, and the best available medium-quality path.
  Its result reports when an already-compact PDF did not become smaller.

## What You Can Do

Once installed, just talk to your AI assistant naturally:

```
"Merge report1.pdf and report2.pdf"
"Split this PDF into pages 1-3 and 5"
"Encrypt this PDF with password mypass123"
"Add a DRAFT watermark to this PDF"
"Convert these JPG images to a single PDF"
"Extract all tables from this PDF"
"Convert this Markdown file to PDF"
```

## All 97 Tools

### Organize & Manage (12)
`merge` · `split` · `extract_pages` · `delete_pages` · `sort_pages` · `reverse_pages` · `add_blank_page` · `rotate` · `alternate_merge` · `view_metadata` · `edit_metadata` · `page_dimensions`

### Edit & Annotate (7)
`watermark` · `page_number` · `add_header_footer` · `add_stamps` · `crop_pdf` · `flatten_pdf` · `bates_number_pdf`

### Optimize & Security (6)
`compress` · `encrypt` · `decrypt` · `redact_pdf` · `remove_metadata` · `invert_colors`

### Convert — Image → PDF (9)
`image_to_pdf` · `jpg_to_pdf` · `png_to_pdf` · `webp_to_pdf` · `bmp_to_pdf` · `tiff_to_pdf` · `svg_to_pdf` · `heic_to_pdf` · `psd_to_pdf`

### Convert — PDF → Image (6)
`pdf_to_png` · `pdf_to_jpg` · `pdf_to_webp` · `pdf_to_bmp` · `pdf_to_tiff` · `pdf_to_zip`

### Document Conversion (10)
`markdown_to_pdf` · `pdf_to_markdown` · `txt_to_pdf` · `json_to_pdf` · `email_to_pdf` · `cbz_to_pdf` · `epub_to_pdf` · `rtf_to_pdf` · `pdf_to_greyscale` · `pdf_to_pdfa`

### Page Layout (7)
`divide_pages` · `combine_single_page` · `nup_pdf` · `pdf_booklet` · `posterize_pdf` · `grid_combine` · `fix_page_size`

### Analysis & Info (9)
`pdf_reader` · `get_page_text` · `pdf_search` · `get_pdf_chunks` · `compare_pdfs` · `remove_blank_pages` · `pdf_to_json` · `extract_tables` · `table_of_contents`

### Annotations & Metadata (6)
`edit_bookmarks` · `extract_attachments` · `remove_annotations` · `background_color` · `change_permissions` · `ocg_manager`

### Optimize (4)
`repair_pdf` · `linearize_pdf` · `sanitize_pdf` · `remove_restrictions`

### Forms & Signing (3)
`sign_pdf` · `form_filler` · `form_creator`

### AI Tools (3)
`ai_summarize` · `ai_chat_with_pdf` · `ai_extract_info`

### Specialized (6)
`deskew_pdf` · `rasterize_pdf` · `extract_images` · `add_attachments` · `edit_attachments` · `font_to_outline`

### External Tools (9) — require LibreOffice/Calibre/DjVuLibre
`word_to_pdf` · `excel_to_pdf` · `powerpoint_to_pdf` · `pdf_to_docx` · `pdf_to_excel` · `pdf_to_ppt` · `mobi_to_pdf` · `djvu_to_pdf` · `xps_to_pdf`

Core tools process files locally. Nine document-conversion tools use optional
LibreOffice, Calibre, or DjVuLibre installations; `system_status` reports their
availability before an Agent starts a workflow.

## Requirements

- Node.js 20.9+
- Claude Desktop, Cursor, Windsurf, or Claude Code
- Optional: LibreOffice, Calibre, DjVuLibre, Ghostscript, and veraPDF for
  specialized conversions and validation

## Development

```bash
git clone https://github.com/WendongAI/onepdf-mcp-server.git
cd onepdf-mcp-server
npm install
npm run build          # TypeScript build
npm test               # native tools + quality + runtime + MCP E2E
npm run test:package   # install and start the packed npm tarball
```

## License

MIT © [1pdf](https://1pdf.best)