Skip to main content
Glama
Sign In
pdf-merger-mcp-server

pdf-merger-mcp-server

by NikhilBelwate
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

PDF Merger MCP Server

An MCP (Model Context Protocol) server that exposes the PDF Merger App as a set of tools any MCP-compatible LLM client can use to upload, arrange, merge, and download PDFs.

Tools

Tool

Description

pdf_merger_upload_pdfs

Upload one or more PDF files from disk to the merger service

pdf_merger_remove_file

Remove a file from an upload session

pdf_merger_merge

Merge uploaded PDFs in a specified order

pdf_merger_get_download_url

Build a one-time download URL for the merged result

Related MCP server: context-retrieval

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run (stdio transport — default)
PDF_MERGER_API_URL=http://localhost:3000 npm start

# Run (HTTP transport for remote access)
TRANSPORT=http PORT=4000 PDF_MERGER_API_URL=http://localhost:3000 npm start

Environment Variables

Variable

Default

Description

PDF_MERGER_API_URL

http://localhost:3000

Base URL of the PDF Merger App API

TRANSPORT

stdio

Transport mode: stdio or http

PORT

4000

HTTP server port (only when TRANSPORT=http)

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pdf-merger": {
      "command": "node",
      "args": ["/path/to/pdf-merger-mcp-server/dist/index.js"],
      "env": {
        "PDF_MERGER_API_URL": "https://your-merger-app.vercel.app"
      }
    }
  }
}

Typical Workflow

  1. Upload PDFs → returns session_id + file IDs

  2. Remove unwanted files (optional)

  3. Merge with desired file order → returns one-time download token

  4. Download using the token URL

Architecture

LLM Client ──MCP──▶ pdf-merger-mcp-server ──HTTP──▶ PDF Merger App (Express)
                     (stdio or HTTP)                  (Vercel Blob + pdf-lib)

Development

npm run dev    # Auto-reload via tsx watch
npm run build  # Compile TypeScript → dist/
npm run clean  # Remove dist/

Available Tools

4 tools
pdf_merger_get_download_urlGet Download URLA
Read-onlyIdempotent

Build a one-time download URL for a merged PDF.

The token is returned by pdf_merger_merge. Each token can only be used once; after the first download the link expires and all associated cloud files are cleaned up.

Args:

  • token (string): One-time download token UUID from the merge response.

Returns (JSON): { "download_url": "https://your-api.example.com/download/" }

Notes:

  • Opening the URL in a browser triggers a file download of "merged.pdf".

  • After download, source blobs are automatically deleted from cloud storage.

Inputs: token (required).

pdf_merger_mergeMerge PDFsA

Merge previously uploaded PDFs in a specified order into a single PDF.

Returns a one-time download token. Use pdf_merger_get_download_url to build the download link. The session is consumed after merging — re-upload files to merge again.

Args:

  • session_id (string): UUID of the upload session.

  • file_order (string[]): Ordered array of file UUIDs. The first entry becomes the first pages of the merged output. Must contain at least 2 file IDs and at most 30.

Returns (JSON): { "token": "uuid", "page_count": 45, "size_formatted": "2.3 MB", "download_url": "https://..." }

Workflow:

  1. Upload PDFs using pdf_merger_upload_pdfs

  2. (Optional) Remove unwanted files using pdf_merger_remove_file

  3. Merge using this tool with desired file order

  4. Use the returned download_url to download the merged PDF

Error Handling:

  • Session not found → 404

  • File order contains unknown IDs → 400

  • Encrypted/corrupt PDF → 422

  • Less than 2 files → 400

Inputs: file_order (required), session_id (required).

pdf_merger_remove_fileRemove File from SessionA
DestructiveIdempotent

Remove a single PDF file from an upload session on the PDF Merger service.

The file is permanently deleted from cloud storage. This operation cannot be undone.

Args:

  • session_id (string): UUID of the session containing the file.

  • file_id (string): UUID of the file to remove.

Returns (JSON): { "success": true }

Error Handling:

  • Session not found → 404 error

  • File not found in session → 404 error

Inputs: file_id (required), session_id (required).

pdf_merger_upload_pdfsUpload PDFsA

Upload one or more PDF files to the PDF Merger service for later merging.

Each file must be a valid PDF (≤100 MB). Up to 30 files can be uploaded per session. If session_id is provided, files are appended to that existing session; otherwise a new session is created.

Args:

  • file_paths (string[]): Absolute paths to PDF files on disk.

  • session_id (string, optional): UUID of existing session to append to.

Returns (JSON): { "session_id": "uuid", "files": [ { "id": "uuid", "name": "doc.pdf", "size": 102400, "sizeFormatted": "100.0 KB" } ] }

Examples:

  • Upload two files to a new session: file_paths=["/tmp/report.pdf", "/tmp/appendix.pdf"]

  • Append to existing session: file_paths=["/tmp/extra.pdf"], session_id="550e8400-..."

Error Handling:

  • File not found on disk → clear message with the missing path

  • Non-PDF file → 415 error from API

  • File >100 MB → 413 error from API

  • 30 files in session → 400 error from API

Inputs: file_paths (required), session_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: upload, remove, merge, and get download URL. There is no overlap in functionality, and the descriptions reinforce the boundaries between them.

    Naming Consistency5/5

    All tool names follow a consistent prefix+verb_noun pattern (pdf_merger_remove_file, pdf_merger_upload_pdfs, pdf_merger_get_download_url). The single exception, pdf_merger_merge, is still a clear verb and fits the overall style.

    Tool Count5/5

    Four tools is a well-scoped size for a PDF merging service. Each tool covers a necessary step in the workflow without redundancy or bloat.

    Completeness4/5

    The core workflow (upload, remove, merge, download) is covered. However, there is no tool to list the current files in a session, which would be needed if an agent needs to reference file IDs without having just uploaded them. This is a minor but notable gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • pdfeverything

      Lezheng2333
      F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to perform 13 PDF operations (merge, split, compress, watermark, encrypt, and more) on local files via MCP.
      3
      -

    • MinerU v4 MCP Server

      Sky6662025
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible agents to convert PDFs and images into Markdown, JSON, HTML, LaTeX, DOCX, or ZIP by wrapping a document parsing service's REST API as callable tools, including uploads, parsing jobs, progress polling, and result downloads.
      1
      Apache 2.0

    • pdfport

      CloudCorpRecords
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables extracting text and metadata from local PDF files, inspecting page and file information, merging multiple PDFs, and splitting PDFs into single-page documents through MCP tools.
      74 npm
      MIT