# PDFluent MCP server

> Lets an AI client read, search, and fill local PDF documents as markdown, text, tables, or forms while keeping data on your machine.

- Repository: https://github.com/pdfluent/pdfluent-mcp
- Page: https://hostedmcp.org/servers/pdfluent/pdfluent-mcp
- Transport: stdio
- Stars: 0
- License: AGPL-3.0
- Latest version: 0.3.0

## Install

### Claude Code

```sh
claude mcp add pdfluent-mcp -- uvx pdfluent-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "pdfluent-mcp": {
      "command": "uvx",
      "args": [
        "pdfluent-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "pdfluent-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pdfluent-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"pdfluent-mcp","type":"stdio","command":"uvx","args":["pdfluent-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "pdfluent-mcp": {
      "command": "uvx",
      "args": [
        "pdfluent-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add pdfluent-mcp -- uvx pdfluent-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.pdfluent-mcp]
command = "uvx"
args = ["pdfluent-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user pdfluent-mcp uvx -- pdfluent-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "pdfluent-mcp": {
      "command": "uvx",
      "args": [
        "pdfluent-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PDFLUENT_MCP_MAX_BYTES` | no | no | Largest document the server opens, in bytes (default 104857600). |
| `PDFLUENT_MCP_MAX_OUTPUT_CHARS` | no | no | Longest result one call returns, in characters (default 200000). |
| `PDFLUENT_MCP_MAX_PAGES` | no | no | Pages one call may read (default 200). |

## Tools (9)

- `extract_markdown`: A local PDF as markdown, in reading order. Headings become ``#`` to ``###``, list items ``-`` and ``1.``, a table a pipe table (or HTML where markdown cannot hold its shape), and a change of page an HTML comment. Running heads and page numbers are left out. Args: path: The PDF's absolute path on this machine. pages: The 0-based pages to return; omit for the whole document, up to the server's page limit. The whole document is still read, because what a block is gets decided against the rest of it. quality: ``"fast"`` (default) or ``"balanced"``, the layout-model tier, which needs the models installed on this machine. (read-only)
- `extract_text`: The plain text layer of a local PDF, page by page. Each page starts with ``<!-- page N -->`` (N 0-based). No reading-order repair and no structure: use extract_markdown for that. A page with no text layer (a scan) yields nothing here; get_metadata names those pages. Args: path: The PDF's absolute path on this machine. pages: The 0-based pages to return; omit for the whole document, up to the server's page limit. (read-only)
- `extract_tables`: The tables of a local PDF as rows of cell text. ``tables`` holds one entry per table in reading order: ``page`` (0-based), ``rows`` (a list of rows, each a list of cell strings, every row the table's width) and ``header_rows`` (how many leading rows are header rows). A spanning cell sits at its first row and column; the cells it covers are empty strings. Args: path: The PDF's absolute path on this machine. pages: The 0-based pages to look at; omit for the whole document, up to the server's page limit. (read-only)
- `extract_blocks`: A local PDF as blocks, in reading order, with where each one came from. Each block has ``kind`` (paragraph, heading, list_item, table_cell, header, footer), ``text``, ``page`` (0-based), ``bbox`` ([x0, y0, x1, y1] in PDF points, origin bottom-left) and ``confidence``: the probability of the learned model that decided the block's kind, or null where no model did -- null means unknown, not low. Headings carry ``level``, list items ``level`` and ``ordinal``, table cells ``row``, ``column``, ``row_span``, ``column_span`` and ``header``. ``pages_needing_vision`` lists the pages in the window whose text layer is missing: nothing this returns for them is the page's content. Args: path: The PDF's absolute path on this machine. pages: The 0-based pages to return; omit for the whole document, up to the server's page limit. include_furniture: Keep running heads and page numbers (kinds header and footer); they are left out by default because they repeat on every page and crowd out the content. (read-only)
- `get_metadata`: What a local PDF is, before reading it. ``pages``, ``title``, ``author``, ``subject``, ``created``, ``modified``, ``format`` (the PDF version), ``encrypted`` with the ``encryption`` filter name, ``has_forms`` with the ``form_fields`` count, the number of ``signatures`` and ``bookmarks``, and ``pages_needing_vision``: the 0-based pages that draw ink but carry no text layer. A document that needs a password to open answers ``encrypted: true`` and ``needs_password: true`` and nothing else. Args: path: The PDF's absolute path on this machine. (read-only)
- `search`: The pages of a local PDF that mention ``query``, with a snippet each. ``pages`` lists every matching 0-based page. ``snippets`` gives up to three windows of text around the match on each of the first twenty matching pages, so an agent can decide which pages to read in full with extract_markdown. Matching is case-insensitive on the text layer; a scanned page cannot match. Args: path: The PDF's absolute path on this machine. query: The text to look for, as written in the document. (read-only)
- `list_form_fields`: The interactive form fields of a local PDF. ``fields`` holds one entry per field: ``name`` (the fully qualified name fill_form takes), ``type`` (text, button, choice, signature or unknown), ``value`` (the current value, or null) and ``page`` (0-based, or null when the field has no widget on a page). An empty list means the document has no AcroForm fields. Args: path: The PDF's absolute path on this machine. (read-only)
- `fill_form`: Fill the form fields of a local PDF and write the result to a new file. ``values`` maps a field name from list_form_fields to its new value: a string for a text field, a check box or a combo box, a list of strings for a multi-select list box. The input file is never changed; ``out_path`` must be a different path inside an allowed root, and one that does not exist yet unless ``overwrite`` is true. A symbolic link at ``out_path`` is refused either way. The result names the fields that were ``set`` and the names that were ``unknown``; nothing is written when no field was set. Args: path: The absolute path of the PDF to fill. values: Field name to new value. out_path: The absolute path to write the filled PDF to. overwrite: Replace a file that already exists at out_path.
- `vision_advice`: Which pages of a local PDF are worth sending to a vision model, and why. ``advice`` holds one entry per page. ``needs_vision`` is true when any reason holds. Today only ``no_text_layer`` is measured -- the page draws ink but yields no text, as a scan does; ``low_confidence_table`` and ``figure`` are always false until the engine can measure them. Args: path: The PDF's absolute path on this machine. (read-only)

## FAQ

### Are my documents uploaded to a server?

No, the server runs on your machine and your documents stay on your machine; they are never uploaded.

### What formats can the server extract from a PDF?

The server can extract content as markdown, plain text, tables, or positioned blocks.
