Stirling-PDF MCP - Nexol MCP Service

🚀 개요

Stirling-PDF는 Docker 기반의 셀프 호스팅 PDF 도구 모음입니다. Nexol에서는 이를 MCP 서버로 래핑하여 Claude Code에서 PDF 작업을 직접 수행할 수 있습니다.

도메인

pdf.nexol.co.kr

MCP 도구

24개

버전

v0.29.0

인증

GitLab OAuth + API Key

3가지 접근 경로를 지원합니다:

경로	설명
Web UI	`https://pdf.nexol.co.kr` 에서 브라우저로 접속 (GitLab OAuth SSO)
REST API	`X-API-KEY` 헤더를 통한 직접 API 호출
MCP (Claude Code)	MCP Gateway를 통한 AI 에이전트 연동 (24개 도구)

📡 접근 방법

# 1. API Key 발급 요청 (roy.cho@nexol.co.kr)
# 2. MCP Gateway에 연결 (Stirling-PDF 포함)
claude mcp add --transport sse nexol-mcp "https://mcp.nexol.co.kr/sse?key=YOUR_API_KEY"

💡 MCP Gateway 통합
Stirling-PDF MCP는 Nexol MCP Gateway에 포함되어 있습니다. Gateway 연결만으로 24개 PDF 도구를 모두 사용할 수 있습니다.

🛠️ MCP 도구 (24개)

merge_pdfs split_pdf extract_pages remove_pages rotate_pdf scale_pages add_watermark add_stamp add_password remove_password pdf_to_image image_to_pdf pdf_to_word office_to_pdf url_to_pdf ocr_pdf compress_pdf get_pdf_info change_metadata add_page_numbers flatten_pdf extract_images add_image get_server_status

📑 병합 / 분할

merge_pdfs

여러 PDF를 하나로 병합합니다.

split_pdf

PDF를 여러 파일로 분할합니다.

extract_pages

특정 페이지만 추출합니다.

remove_pages

특정 페이지를 삭제합니다.

🔄 회전 / 레이아웃

rotate_pdf

페이지 회전 (90/180/270도)

scale_pages

페이지 크기를 조정합니다.

🔒 워터마크 / 보안

add_watermark

텍스트/이미지 워터마크를 추가합니다.

add_stamp

스탬프를 추가합니다.

add_password

비밀번호 보호를 설정합니다.

remove_password

비밀번호를 제거합니다.

🔄 변환

pdf_to_image

PDF → 이미지 (PNG/JPEG/GIF/TIFF)

image_to_pdf

이미지 → PDF 변환

pdf_to_word

PDF → Word (DOCX/DOC/ODT)

office_to_pdf

Office → PDF (Word/Excel/PPT)

url_to_pdf

URL → PDF 변환

👁️ OCR / 압축

ocr_pdf

광학 문자 인식 (한/영/일 지원)

compress_pdf

PDF 파일 크기 축소 (1~5 레벨)

✏️ 메타데이터 / 편집

get_pdf_info

PDF 정보를 조회합니다.

change_metadata

메타데이터를 수정합니다.

add_page_numbers

페이지 번호를 추가합니다.

flatten_pdf

폼 필드를 평탄화합니다.

extract_images

PDF에서 이미지를 추출합니다.

add_image

PDF에 이미지를 삽입합니다.

⚙️ 유틸리티

get_server_status

Stirling-PDF 서버 상태를 확인합니다.

💬 사용 예시

Claude에게 자연어로 요청하면 적절한 도구를 자동으로 선택합니다:

# PDF 정보 조회
"이 PDF 파일 정보 알려줘"

# PDF 병합
"part1.pdf와 part2.pdf를 합쳐줘"

# OCR (한국어 + 영어)
"이 스캔된 PDF에서 텍스트 추출해줘"

# URL을 PDF로 변환
"https://example.com 페이지를 PDF로 저장해줘"

# PDF 압축
"이 PDF 파일 크기를 줄여줘"

# 워터마크 추가
"이 PDF에 '대외비' 워터마크 넣어줘"

MCP 도구 직접 호출

// PDF 정보 조회
get_pdf_info({ fileInput: { data: "base64...", filename: "doc.pdf" } })

// PDF 병합
merge_pdfs({
  files: [
    { data: "base64...", filename: "part1.pdf" },
    { data: "base64...", filename: "part2.pdf" }
  ]
})

// OCR (한국어 + 영어)
ocr_pdf({
  fileInput: { data: "base64...", filename: "scanned.pdf" },
  languages: ["kor", "eng"]
})

// URL → PDF 변환
url_to_pdf({ urlInput: "https://example.com" })

// PDF 압축 (레벨 1~5, 높을수록 강력)
compress_pdf({
  fileInput: { data: "base64...", filename: "large.pdf" },
  optimizeLevel: 4
})

🌐 REST API 엔드포인트

MCP 외에도 X-API-KEY 헤더로 REST API를 직접 호출할 수 있습니다.

# 서버 상태 확인
curl -s https://pdf.nexol.co.kr/api/v1/info/status

# PDF 정보 조회 (API Key 인증)
curl -s -X POST https://pdf.nexol.co.kr/api/v1/security/get-info-on-pdf \
  -H "X-API-KEY: your-api-key" \
  -F "fileInput=@document.pdf"

# URL → PDF 변환
curl -s -X POST https://pdf.nexol.co.kr/api/v1/convert/url/pdf \
  -H "X-API-KEY: your-api-key" \
  -F "urlInput=https://example.com" \
  -o output.pdf

General

메서드	경로	설명
POST	`/api/v1/general/merge-pdfs`	PDF 병합
POST	`/api/v1/general/split-pages`	PDF 분할/페이지 추출
POST	`/api/v1/general/remove-pages`	페이지 삭제
POST	`/api/v1/general/rotate-pdf`	페이지 회전
POST	`/api/v1/general/scale-pages`	페이지 크기 조정
POST	`/api/v1/general/crop`	페이지 크롭
POST	`/api/v1/general/rearrange-pages`	페이지 재배치
POST	`/api/v1/general/overlay-pdfs`	PDF 오버레이
POST	`/api/v1/general/multi-page-layout`	다중 페이지 레이아웃

Convert

메서드	경로	설명
POST	`/api/v1/convert/file/pdf`	파일 → PDF
POST	`/api/v1/convert/img/pdf`	이미지 → PDF
POST	`/api/v1/convert/pdf/img`	PDF → 이미지
POST	`/api/v1/convert/pdf/word`	PDF → Word
POST	`/api/v1/convert/pdf/html`	PDF → HTML
POST	`/api/v1/convert/pdf/text`	PDF → 텍스트
POST	`/api/v1/convert/pdf/csv`	PDF → CSV
POST	`/api/v1/convert/pdf/xml`	PDF → XML
POST	`/api/v1/convert/pdf/pdfa`	PDF → PDF/A
POST	`/api/v1/convert/url/pdf`	URL → PDF

Security

메서드	경로	설명
POST	`/api/v1/security/add-password`	비밀번호 추가
POST	`/api/v1/security/remove-password`	비밀번호 제거
POST	`/api/v1/security/add-watermark`	워터마크 추가
POST	`/api/v1/security/get-info-on-pdf`	PDF 정보 조회
POST	`/api/v1/security/sanitize-pdf`	PDF 살균
POST	`/api/v1/security/auto-redact`	자동 수정

Misc

메서드	경로	설명
POST	`/api/v1/misc/ocr-pdf`	OCR 수행
POST	`/api/v1/misc/compress-pdf`	PDF 압축
POST	`/api/v1/misc/add-page-numbers`	페이지 번호 추가
POST	`/api/v1/misc/add-stamp`	스탬프 추가
POST	`/api/v1/misc/add-image`	이미지 추가
POST	`/api/v1/misc/extract-images`	이미지 추출
POST	`/api/v1/misc/flatten`	폼 평탄화
POST	`/api/v1/misc/update-metadata`	메타데이터 수정
POST	`/api/v1/misc/repair`	PDF 복구

Info

메서드	경로	설명
GET	`/api/v1/info/status`	서버 상태
GET	`/api/v1/info/uptime`	가동 시간
GET	`/api/v1/info/load`	서버 부하

🏗️ 인프라 구성

항목	값
이미지	`frooodle/s-pdf:0.29.0`
내부 포트	`127.0.0.1:8010` → `8080`
도메인	`pdf.nexol.co.kr` (Let's Encrypt SSL)
인증	GitLab OAuth + API Key
헬스체크	`/api/v1/info/status` (30초 간격)
로케일	`ko_KR`
OCR	Tesseract (한/영/일)
업로드 제한	100MB (Nginx `client_max_body_size`)

아키텍처

Claude Code ──stdio──▷ MCP Gateway ──spawn──▷ MCP Server (24 tools)
                                                                    │
Browser ──HTTPS──▷ GitLab OAuth ──▷ Nginx (pdf.nexol.co.kr:443)    │
                                            │                       │
curl/SDK ──API Key──────────────────────────┘                       │
                                            ▽                       ▽
                                    ┌──────────────────────────────────┐
                                    │  Stirling-PDF v0.29.0            │
                                    │  Docker (127.0.0.1:8010→8080)    │
                                    └──────────┬───────────────────────┘
                                               │
                              ┌────────┬───────┴───────┬──────────┐
                              ▽        ▽               ▽          ▽
                          configs/  tessdata/       logs/     pipeline/
                                    (kor+eng+jpn)

⚙️ MCP 서버 설정

Gateway 설정 (mcp-config.json)

{
  "stirling-pdf": {
    "command": "node",
    "args": ["/app/internal/stirling-pdf/dist/index.js"],
    "env": {
      "STIRLING_PDF_URL": "https://pdf.nexol.co.kr",
      "STIRLING_PDF_API_KEY": "<OpenBao에서 가져온 키>",
      "DEBUG": "false"
    },
    "enabled": true,
    "mode": "hot"
  }
}

직접 사용 (Claude Code settings.json)

{
  "mcpServers": {
    "stirling-pdf": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "STIRLING_PDF_URL": "https://pdf.nexol.co.kr",
        "STIRLING_PDF_API_KEY": "your-api-key"
      }
    }
  }
}

MCP 빌드

cd mcp
npm install
npm run build   # dist/index.js 생성

⚠️ API Key 필요

Stirling-PDF API Key는 OpenBao에서 관리됩니다. 발급이 필요하면 관리자에게 문의하세요.

🔧 운영

헬스체크

# Docker 헬스체크 (자동, 30초 간격)
docker inspect --format='{{.State.Health.Status}}' stirling-pdf

# 수동 확인
curl -s https://pdf.nexol.co.kr/api/v1/info/status | jq .

로그 확인

docker logs stirling-pdf --tail 100 -f

업데이트

cd /docker_service/stirling-pdf
# docker-compose.yml에서 이미지 태그 변경 후
docker compose pull && docker compose up -d

참고
Watchtower 자동 업데이트는 비활성화되어 있습니다. DIUN을 통해 새 버전 알림만 수신합니다.

📖 관련 문서

서비스	URL	설명
Stirling-PDF	pdf.nexol.co.kr	PDF 처리 서비스 (Web UI)
GitLab 소스	231_server/pdf	설정 및 MCP 소스 코드
원본 프로젝트	Stirling-Tools/Stirling-PDF	오픈소스 원본 (AGPL-3.0)