mcp-pdf-processor

A robust Go-based project that wraps the pdfcpu library to provide PDF processing capabilities via CLI, Model Context Protocol (MCP), and Agent Development Kit (ADK).

Features

• Multi-Interface: Access PDF operations via standard CLI, MCP tools, or ADK functions.
• Zero-Dependency CLI: Handcrafted command registry using only the Go standard library.
• CGO-Free: 100% pure Go for easy cross-compilation and safety.
• JSON First:
  • Extract PDF info and forms to JSON.
  • Generate PDFs from JSON configurations.
  • Export JSON Schema for PDF creation.
• Extensive Command Set: Supports merge, split, extract, trim, rotate, watermark, optimize, and more.

Installation & Build

Ensure you have Go installed (1.21+ recommended).

# Clone the repository
git clone https://github.com/innomon/mcp-pdf-processor
cd mcp-pdf-processor

# Build the binary (CGO-free)
CGO_ENABLED=0 go build -o mcp-pdf-processor main.go

Usage

CLI Usage

The CLI uses a command [flags] [args] structure.

# Get PDF info
./mcp-pdf-processor info document.pdf

# Merge multiple PDFs
./mcp-pdf-processor merge output.pdf in1.pdf in2.pdf

# Convert JSON to PDF
./mcp-pdf-processor json-to-pdf config.json output.pdf

# Export JSON Schema
./mcp-pdf-processor schema > pdf-schema.json

MCP Usage

To use this as an MCP server (e.g., in Claude Desktop or Gemini CLI), point your configuration to the built binary with the serve-mcp command.

Claude Desktop Configuration:

{
  "mcpServers": {
    "pdf-processor": {
      "command": "/path/to/mcp-pdf-processor",
      "args": ["serve-mcp"]
    }
  }
}

ADK & Agentic Usage

The project leverages the Agentic framework to provide a sophisticated agent hierarchy and interactive interfaces for PDF processing.

The serve-adk command supports dynamic configuration via a config.yaml file and provides multiple launch modes.

# Start the ADK server with a specific configuration
./mcp-pdf-processor serve-adk config.yaml

# Start in interactive console mode
./mcp-pdf-processor serve-adk -console config.yaml

# Enable the Web UI and API server
./mcp-pdf-processor serve-adk -webui -api config.yaml

Key Agentic Features:

• Tool Mapping: All PDF operations (merge, split, info, etc.) are automatically registered as builtin tools for your agents.
• Agent Hierarchy: Define complex agent behaviors and sub-agent relationships in config.yaml.
• Interactive Interfaces: Built-in support for Web UI, A2A (Agent-to-Agent), and Console launchers.

See example-agentic-config.yaml for a starting point.

Architecture

1. Operation Layer (internal/operations): Defines the Operation interface. All business logic calling pdfcpu is contained here, making it agnostic to the transport layer.
2. CLI Layer (internal/cli): A handcrafted registry that maps CLI arguments to Operations.
3. MCP Layer (internal/mcp): Uses the official modelcontextprotocol/go-sdk to expose Operations as JSON-RPC tools.
4. ADK Layer (internal/adk): Uses google.golang.org/adk to wrap Operations as function tools for LLM agents.

License

Copyright 2026 Innomon

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.