使用说明

mcp-go-pdf-tools

Suite en Go para manipular PDFs mediante servidor MCP stdio, API HTTP y CLI. Incluye información, división, compresión, eliminación/extracción de páginas y fusión.

Estado: herramientas MCP, endpoints HTTP y comandos CLI disponibles. Consulta la sección de seguridad para límites y requisitos de despliegue.

Estructura importante

cmd/server: servidor HTTP (endpoints GET /health, POST /api/v1/pdf/split, POST /api/v1/pdf/compress, POST /api/v1/pdf/remove-pages, POST /api/v1/pdf/extract-pages, POST /api/v1/pdf/merge).
cmd/mcp-server: servidor stdio MCP con herramientas pdf_split, pdf_info, pdf_compress, pdf_remove_pages, pdf_extract_pages, pdf_merge.
cmd/cli: herramienta de linea de comandos con subcomandos split, remove-pages, extract-pages y merge.
internal/pdf: logica para manipular PDFs (usa pdfcpu). Incluye funciones para split, compresion y eliminacion de paginas.
examples: cliente de ejemplo para subir un PDF y guardar split.zip.
mcp: notas y ejemplos para integrar con Claude Desktop.

Funcionalidades

pdf_merge

Combina múltiples PDFs en uno. Soporta dos formatos de request:

Nuevo formato con copias:

{"files":[{"path":"pakinglist.pdf","copies":1},{"path":"albaran.pdf","copies":3}],"output_filename":"combined.pdf"}

Formato legacy (1 copia por archivo):

{"paths":["file1.pdf","file2.pdf"],"output_filename":"combined.pdf"}

pdf_split

Divide un PDF en archivos de una pagina cada uno. Puede crear un ZIP con las paginas.

pdf_info

Devuelve informacion basica del PDF (paginas, tamano).

pdf_compress

Reescribe y optimiza un PDF con pdfcpu. El tamaño final y los cambios de metadatos dependen del documento.

pdf_remove_pages

Elimina o conserva paginas especificas de un PDF. Soporta rangos de paginas con la sintaxis 2,5-8,11.

Dos modos de operacion:

remove (por defecto): elimina las paginas indicadas y conserva el resto.
keep: conserva solo las paginas indicadas y elimina el resto.

Ejemplos de seleccion:

"5" — solo la pagina 5
"1-3" — paginas 1, 2 y 3
"2,5-8,11" — paginas 2, 5, 6, 7, 8 y 11
"7-10,61-66,77,80" — paginas 7-10, 61-66, 77 y 80

pdf_extract_pages

Crea un PDF nuevo con solo las paginas del original que elijas (el original no se modifica). Equivale a pdf_remove_pages con mode=keep, pero como herramienta independiente pensada para extraccion. Soporta la misma sintaxis de rangos que pdf_remove_pages; el orden de salida sigue siempre el orden original y las paginas repetidas en la seleccion se ignoran.

Guía de uso para MCP

El servidor MCP stdio opera sobre archivos locales accesibles para el proceso que lo ejecuta; úsalo solo con clientes de confianza y proporciona rutas absolutas.

Usa pdf_info para consultar el total de páginas antes de elegir rangos si no lo conoces.
Usa pdf_remove_pages para generar una copia quitando páginas (remove) o conservando solo las seleccionadas (keep). Usa pdf_extract_pages para crear un PDF nuevo y conservar el original.
Los rangos son inclusivos, por ejemplo 1,3-5; los duplicados se ignoran y el resultado conserva el orden original.
Todas las salidas deben ser distintas de las entradas y no existir previamente. El servidor no sobrescribe archivos.
pdf_split crea una salida por página. Sin output_dir, devuelve las rutas de una carpeta temporal; zip_name es solo un nombre de archivo. zip_b64 admite ZIP de hasta 32 MiB.
pdf_merge combina de 2 a 50 PDFs, con un máximo agregado predeterminado de 500 MiB. El límite por PDF es 200 MiB y el de páginas es 10 000 por defecto.
pdf_compress optimiza con pdfcpu; la reducción de tamaño y los cambios de metadatos dependen del documento.

Dependencias clave

github.com/pdfcpu/pdfcpu — usado para manipulacion de PDFs (split, compresion, informacion, eliminacion de paginas).

Quick Start (desarrollo)

Build y run (desarrollo):

cd C:\MCPs\clone\mcp-go-pdf-tools\cmd\server
go run .

Build de todos los binarios:

go build -o bin/server.exe ./cmd/server/
go build -o bin/mcp-server.exe ./cmd/mcp-server/
go build -o bin/cli.exe ./cmd/cli/

Endpoints HTTP

Split

curl -F "file=@test.pdf" http://localhost:8080/api/v1/pdf/split --output split.zip

Compress

curl -F "file=@test.pdf" http://localhost:8080/api/v1/pdf/compress --output compressed.pdf

Ver informacion de compresion en headers:

curl -I -F "file=@test.pdf" http://localhost:8080/api/v1/pdf/compress
# Mostrara X-Original-Size, X-Compressed-Size, X-Reduction-Percent

Remove Pages

Eliminar paginas 2, 5-8 y 11:

curl -F "file=@test.pdf" -F "pages=2,5-8,11" -F "mode=remove" http://localhost:8080/api/v1/pdf/remove-pages --output result.pdf

Conservar solo paginas 1-3 y 10:

curl -F "file=@test.pdf" -F "pages=1-3,10" -F "mode=keep" http://localhost:8080/api/v1/pdf/remove-pages --output result.pdf

Extract Pages

Crear un PDF nuevo solo con las paginas 1, 3 y 10:

curl -F "file=@test.pdf" -F "pages=1,3,10" http://localhost:8080/api/v1/pdf/extract-pages --output seleccion.pdf

CLI

Split

.\bin\cli.exe split -i test.pdf -outdir output
.\bin\cli.exe split -i test.pdf -zip split.zip

Remove Pages

Eliminar paginas 2, 5-8 y 11:

.\bin\cli.exe remove-pages -i test.pdf -o result.pdf -pages "2,5-8,11"

Conservar solo paginas 1, 3 y 5 (eliminar el resto):

.\bin\cli.exe remove-pages -i test.pdf -o result.pdf -pages "1,3,5" -mode keep

Ejemplo real — conservar solo paginas especificas de un libro:

.\bin\cli.exe remove-pages -i libro.pdf -o seleccion.pdf -pages "7-10,61-66,77,80,119-124" -mode keep

Extract Pages

Crear un PDF nuevo solo con las paginas 1, 3 y 5:

.\bin\cli.exe extract-pages -i test.pdf -o seleccion.pdf -pages "1,3,5"

Ejemplo real — extraer paginas especificas de un libro a un PDF nuevo:

.\bin\cli.exe extract-pages -i libro.pdf -o seleccion.pdf -pages "7-10,61-66,77,80,119-124"

Docker

Construir imagen local:

docker build -t mcp-pdf-server:local .

Ejecutar contenedor:

$token = [guid]::NewGuid().ToString("N")
$workDir = (Get-Location).Path
$cert = Join-Path $workDir "certs\server.crt"
$key = Join-Path $workDir "certs\server.key"
docker run --rm -p 8080:8080 -v "${workDir}:/data:ro" -v "${cert}:/run/tls/server.crt:ro" -v "${key}:/run/tls/server.key:ro" -e "HTTP_AUTH_TOKEN=$token" -e HTTP_ALLOWED_DIR=/data -e HTTP_TLS_CERT_FILE=/run/tls/server.crt -e HTTP_TLS_KEY_FILE=/run/tls/server.key mcp-pdf-server:local

Configuracion y seguridad del servidor HTTP

Por defecto escucha solo en 127.0.0.1.
Para escuchar en una interfaz no local, configura obligatoriamente HTTP_AUTH_TOKEN, HTTP_ALLOWED_DIR, HTTP_TLS_CERT_FILE y HTTP_TLS_KEY_FILE; las rutas de entrada de pdf_merge deben resolver dentro de ese directorio.
HTTP_MAX_UPLOAD_SIZE limita el cuerpo completo de las peticiones; HTTP_MAX_CONCURRENT limita las solicitudes simultaneas.
PDF_MAX_FILE_SIZE (200 MiB por defecto) y PDF_MAX_PAGES (10 000) limitan cada PDF; PDF_MAX_MERGE_SIZE (500 MiB) limita el tamaño agregado de los merges; PDF_TEMP_DIR configura los temporales de pdf_split.
El MCP stdio tiene acceso al sistema de archivos local del usuario que lo ejecuta; úsalo solo con clientes de confianza. El núcleo PDF rechaza destinos iguales a la entrada o que ya existan.

Tests

Ejecutar tests:

go test ./...

Las pruebas de integración usan PDFs de examples/ cuando están disponibles y se omiten si esos documentos no están presentes en el checkout.

Integracion con Claude Desktop (MCP)

Para integrar con Claude Desktop tienes dos opciones principales:

stdio (recomendado para Claude Desktop): ejecutar un proceso mcp-server.exe que hable por stdin/stdout con Claude Desktop. Esto es lo que Claude espera para registrar herramientas automaticamente.
HTTP (alternativa): ejecutar el servidor HTTP y usar un adaptador desde Claude (menos directo).

Ejemplo de fragmento para pegar en claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pdftools": {
      "command": "C:\\MCPs\\clone\\mcp-go-pdf-tools\\bin\\mcp-server.exe",
      "args": [],
      "env": {}
    }
  }
}

Herramientas disponibles via MCP: pdf_split, pdf_info, pdf_compress, pdf_remove_pages, pdf_extract_pages, pdf_merge.

Integración con OpenCode

El servidor PDF usa MCP por stdio, compatible con OpenCode. Desde la raíz del repositorio, compila el ejecutable:

New-Item -ItemType Directory -Force bin | Out-Null
go build -o bin/mcp-server.exe ./cmd/mcp-server

Añade esta entrada a tu opencode.json global o al del proyecto. Si ya tienes un objeto mcp, incorpora solo la entrada pdf-tools sin reemplazar las demás:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pdf-tools": {
      "type": "local",
      "command": ["C:\\MCPs\\clone\\mcp-go-pdf-tools\\bin\\mcp-server.exe"],
      "enabled": true
    }
  }
}

Ajusta command para que apunte a la ruta real del ejecutable. Reinicia OpenCode y comprueba la conexión con:

opencode mcp list

Las herramientas pdf_info, pdf_split, pdf_compress, pdf_remove_pages, pdf_extract_pages y pdf_merge estarán disponibles para el modelo. Para más opciones, consulta la documentación de servidores MCP de OpenCode.

Ejemplos de uso MCP (stdio)

Ejemplo de llamada a pdf_remove_pages con PowerShell (modo keep):

'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pdf_remove_pages","arguments":{"pdf_path":"C:\\\\tmp\\\\libro.pdf","output_path":"C:\\\\tmp\\\\seleccion.pdf","pages":"7-10,61-66,77,80","mode":"keep"}}}' | .\bin\mcp-server.exe

Ejemplo de llamada a pdf_extract_pages (crea un PDF nuevo con solo esas paginas):

'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pdf_extract_pages","arguments":{"pdf_path":"C:\\\\tmp\\\\libro.pdf","output_path":"C:\\\\tmp\\\\seleccion.pdf","pages":"7-10,61-66,77,80"}}}' | .\bin\mcp-server.exe

Ejemplo de llamada a pdf_compress:

'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pdf_compress","arguments":{"pdf_path":"C:\\\\tmp\\\\test.pdf","output_path":"C:\\\\tmp\\\\test-compressed.pdf"}}}' | .\bin\mcp-server.exe

Respuesta MCP (ejemplo):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"original_pages\":357,\"removed_pages\":[1,2,3,...],\"removed_count\":301,\"remaining_pages\":56,\"mode\":\"keep\",\"output_path\":\"C:\\\\tmp\\\\seleccion.pdf\"}"
      }
    ]
  }
}

Roadmap y proximos pasos

Ver Roadmap.md en la raiz del repo para ver lo completado y lo pendiente.

Contacto / ayuda

Para reportar issues o solicitar nuevas funcionalidades, abre un issue en el repositorio.

使用说明

mcp-go-pdf-tools

Funcionalidades

pdf_merge

pdf_split

pdf_info

pdf_compress

pdf_remove_pages

pdf_extract_pages

Guía de uso para MCP

Quick Start (desarrollo)

Endpoints HTTP

Split

Compress

Remove Pages

Extract Pages

CLI

Split

Remove Pages

Extract Pages

Docker

Configuracion y seguridad del servidor HTTP

Tests

Integracion con Claude Desktop (MCP)

Integración con OpenCode

Ejemplos de uso MCP (stdio)

Roadmap y proximos pasos

Contacto / ayuda

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器