Skip to main content
PPDF123

PDF123 MCP servers for AI agents

MCP, the Model Context Protocol, is an open standard that lets AI clients such as Claude Code, Claude Desktop and Cursor call external tools. PDF123 offers a local MCP server, @pdf123/mcp, for files on your machine and a hosted endpoint that uses an API key.

@pdf123/mcpNode 20.3 or newer

Install

npx -y @pdf123/mcp
On this page

Which MCP server should I use?

Both servers expose PDF123 operations. They differ in where they run and how files reach them.

Local: @pdf123/mcpHosted: /mcp
Runs whereOn your machine, started by the MCP client over stdioOn PDF123 servers at https://pdf123.xyz/mcp
InputFile paths on disk. The server uploads them and saves the result next to the inputFiles sent through the upload tool
CredentialsNone for anonymous use. PDFX_API_KEY is optionalX-API-KEY header on every request. Without it the answer is 401
Installnpx -y @pdf123/mcpNothing. Add the URL and header to the client
ToolsSix tools for the full 97-tool catalogSeven tools: describe, convert, pages, misc, security, upload and download
Use it whenAn agent works on documents in a local folderAn agent or hosted service already handles uploads through the API

Use the local server for coding assistants on a laptop. Use the hosted endpoint when the agent runs in the cloud and cannot read your disk.

How do I install the local MCP server?

Nothing needs to be installed, because the MCP client starts the server with npx. In Claude Code, add it with one command.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop reads claude_desktop_config.json, and Cursor reads .cursor/mcp.json. Other clients have an MCP settings page or file. All of them accept the same mcpServers entry.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Restart the client after you change its configuration. To keep a copy on your path, run npm install -g @pdf123/mcp, which provides the pdf123-mcp command. The server needs Node 20.3 or newer and a reachable API base. There is no offline mode.

What do I ask the agent first?

Ask in plain language and name the files. For example:

Merge ~/Documents/a.pdf and ~/Documents/b.pdf, then compress the result.

The agent calls pdf123_run_pipeline, or pdf123_run_tool twice, uploads the files to PDF123, and answers with the path of the saved file. The result is saved next to the first input and never replaces an existing file. The same operations exist as Merge and Compress on the website.

Which tools does the local server offer?

The server has six tools. Tool ids such as merge are plain string arguments, so the tool list stays small.

ToolWhat it doesKey arguments
pdf123_list_toolsLists the tools, one line eachgroup, query, format
pdf123_describe_toolShows a tool's fields, defaults, allowed values and whether it runs as a batchtool
pdf123_run_toolRuns one tool on local files and returns the saved path or the JSON reporttool, files, params, output
pdf123_run_pipelineChains up to 8 tools in one requeststeps, files, output
pdf123_callSends a raw request to any tool id, operation id or /api/... pathtarget, files, fields
pdf123_server_statusShows the server's version, upload limits, OCR page limit and languages, and the operations that are switched offnone

An agent usually calls pdf123_list_tools to find a tool, pdf123_describe_tool to read its fields, and then pdf123_run_tool. pdf123_server_status is worth one call before a large upload or an OCR job. A mistyped id returns "did you mean" suggestions.

How do batches, passwords and pipelines work?

  • Batches. Several files given to a single-file tool run as a batch with one result per file. Each file is saved as it finishes. The reply is a per-file report. If any file fails, the reply is an error with the report attached, so the agent can retry only the failed files.
  • Passwords. input_password opens every encrypted input. passwords sets one password per file, in the same order as files, with an empty string for an open file. This also works for multi-file tools such as Merge.
  • Pipelines. pdf123_run_pipeline takes up to 8 steps, and each step feeds the next. It accepts the same password arguments.
  • Raw calls. pdf123_call reaches operations that are newer than the server. Nothing is validated locally.
  • Filter tools. A tool whose id starts with filter- answers {"matched": false} when its condition does not hold. That is a result, not an error.
  • Retries. idempotencyKey replays the first result for 24 hours.

How do I limit which folders the agent can use?

Set PDFX_MCP_ROOT to a directory. Separate several directories with a colon, or a semicolon on Windows. The server then reads inputs and writes results only inside those directories. Paths outside them, .. escapes and symbolic links that lead out are refused before anything is uploaded, with Code: path_not_allowed. Without this variable, any path the server process can reach is allowed.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Set environment variables in the client's env block, or with claude mcp add -e NAME=value. PDFX_API_BASE points the server at your own pdfx-server instead; see Self-host.

What do results and errors look like?

A single result is a small JSON object with the saved path, the contentType and the size in bytes. When the service reports something about the result it adds headers and notes, such as the size before and after, whether a Compress target size was met, or how many parts of a split are over the size limit. A batch result has processed, unmatched, failed and a files list. These shapes match pdfx --json on the command line. A tool that returns a report, such as Document info, returns the report inline.

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

A failed call comes back as a tool error. Its text ends with Reason:, Code: and Hint: lines when the server supplied them, so an agent can branch on the code.

Error texttext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

If a tool id has a typo, the error lists close ids and ends with Code: unknown_tool. A tool that finds nothing to return, such as pdf-to-csv on a PDF without tables, returns Code: no_content instead of an empty file. See Error codes.

How do I use the hosted MCP endpoint?

The API embeds an MCP server at POST https://pdf123.xyz/mcp. Authenticate with the same X-API-KEY header that the REST API uses. Without a key the endpoint answers 401. Create a key on the Developers page.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

The hosted server lists seven tools: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload and pdf_toolbox_download. Each category tool takes an operation name and its parameters, plus a file or a fileId returned by the upload tool. Use the describe tool to get the schema of one operation.

FAQ

What is MCP?

MCP, the Model Context Protocol, is an open standard for connecting AI clients to external tools. A client such as Claude Code starts or contacts an MCP server, lists its tools, and calls them on the user's behalf.

Does the local MCP server work offline?

No. It uploads files to the PDF123 API, or to the server named in PDFX_API_BASE, and saves the result locally. The API base must be reachable.

Does it need an API key?

The local server does not need a key for anonymous use. Set PDFX_API_KEY if your server requires one. The hosted endpoint at /mcp always needs an X-API-KEY header.

Can the agent read any file on my computer?

By default it can read any path that the server process can reach. Set PDFX_MCP_ROOT to limit reads and writes to the directories you choose.

What happens to my files?

The local server uploads each input to the PDF123 API, or to your own server, for processing. The tool description states that the files are deleted there after processing. The result is saved on your machine. For details, read the file privacy page.

How many tools can an agent use?

The local server reaches all 97 tools in the catalog through six MCP tools. The hosted endpoint groups its operations by category (convert, pages, misc and security) behind seven MCP tools.