To batch convert a folder with an AI agent, point the GroupDocs.Conversion.Mcp server at the folder and describe the job in one sentence. The agent works through the files, calls the conversion engine once per document, and reports what it produced, all locally in Claude, Cursor or GitHub Copilot. It is batch processing driven by a sentence:

Convert every DOCX in my documents folder to PDF, keep the originals

The step‑by‑step version with config and troubleshooting is in the documentation: How to batch-convert a folder of documents with an AI agent. This post walks through the same job as a short session, from the first prompt to handling failures.

저장 폴더부터 시작할까요, 프롬프트부터 시작할까요?

저장 폴더부터 시작합니다. 배치 작업은 폴더 매핑이 성공하거나 실패하는데, 매핑은 각 프롬프트가 아니라 서버 항목에 한 번만 설정됩니다. 두 개의 환경 변수가 이를 제어합니다:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Conversion.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/invoices",
        "GROUPDOCS_MCP_OUTPUT_PATH": "/path/to/invoices/converted"
      }
    }
  }
}

GROUPDOCS_MCP_STORAGE_PATH는 에이전트가 읽을 수 있는 폴더이며, GROUPDOCS_MCP_OUTPUT_PATH는 변환된 파일이 저장되는 위치입니다. 두 경로를 모두 설정하면 원본 폴더는 그대로 유지되고 모든 결과가 converted 폴더에 들어갑니다. 이는 배치 작업을 위한 가장 깔끔한 레이아웃입니다. dnx 명령은 .NET 10 SDK가 필요하고, Docker 이미지 ghcr.io/groupdocs-conversion/conversion-net-mcp:latest는 폴더를 /data 로 마운트합니다. 서버를 등록한 뒤 Claude Desktop, Claude Code, VS Code 또는 Cursor를 재시작하십시오.

첫 번째 프롬프트는 무엇을 하나요?

에이전트에게 가장 단순한 경우를 먼저 알려줍니다:

Convert everything in this folder from DOCX to PDF.

에이전트는 폴더를 열거하고 각 파일에 대해 format: "pdf" 옵션을 사용해 convert 도구를 호출합니다. 각 호출은 저장소에서 파일 이름을 받아 변환된 파일 이름을 반환합니다. 두 번 실행하면 두 번째 실행 시 첫 번째 파일 옆에 새롭고 구분된 파일이 생성됩니다.

필터나 규칙을 어떻게 추가하나요?

프롬프트 자체가 오케스트레이션 레이어입니다. 필터링, 순서 지정 및 오류 정책은 자연어로 표현합니다:

Turn all the PDFs into Markdown; skip files that are already converted.

Convert the invoices to PDF/A for archiving, and list any file that failed.

Make PNG previews of every presentation.

순서를 지정하려면 에이전트가 먼저 get_document_info 를 호출하도록 할 수 있습니다. 이 호출은 변환 없이 파일 유형, 페이지 수 및 기본 속성을 반환합니다:

Check the page count of each PDF first, and only convert the ones with more than 10 pages.

“10 페이지 초과”라는 결정은 에이전트가 내리며, 실제 변환은 엔진이 수행합니다.

하나의 파일이 실패하면 어떻게 되나요?

엔진이 파일을 변환하지 못하면(예: 지원되지 않는 형식이거나 비밀번호가 틀린 경우) 해당 파일에 대한 응답 텍스트는 작업과 이유로 시작합니다. 존재하지 않는 파일 이름을 지정하면 서버가 볼 수 있는 파일 목록을 반환해 에이전트가 스스로 수정할 수 있게 합니다. 보호된 파일의 경우 convert 는 선택적인 password 매개변수를 받습니다.

이 때문에 실패 정책을 프롬프트에 포함시키는 것이 중요합니다. “list any file that failed” 라고 하면 실행이 끝난 뒤 에이전트가 보고서를 제공하므로 실패가 눈에 띄지 않게 넘어가지 않습니다. 보고서를 확인하고 실패한 파일만 다시 실행하십시오.

예시 세션

아래는 축약된 예시 세션입니다. 파일 이름은 가상이며, 응답은 문서화된 동작을 기반으로 구성되었습니다(스크린샷이 아님).

You:    Convert the invoices to PDF/A for archiving, and list any file that failed.
Agent:  [enumerates the invoice files]
Agent:  [calls convert for each file, one at a time]
Agent:  Converted 11 files to the output folder.
        Failed: invoice-0412.docx (password-protected, no password given).

대용량 폴더의 진행 상황을 어떻게 추적하나요?

에이전트는 보통 파일을 하나씩 순차적으로 처리하므로 실행 시간은 파일 수와 크기에 비례합니다. 진행 상황을 보고받고 싶다면 프롬프트에 명시합니다: “tell me after every ten files” 혹은 “summarize at the end”. 몇 백 개 정도의 문서는 문제없이 처리되며 최종 보고서에 어떤 일이 있었는지 기록됩니다. 먼저 작은 부분 집합을 복사해 두고 2~3개의 출력물을 눈으로 확인한 뒤 전체 폴더를 실행하십시오.

배치를 무인으로 실행해야 하면 어떻게 하나요?

에이전트 세션은 사람에 의해 시작되어야 합니다. 일정에 따라 자동화하려면 n8n walkthrough 에서 보여주는 워크플로우 도구가 동일한 서버를 구동하도록 하면 됩니다. 또한 엔진은 GroupDocs.Conversion .NET 라이브러리를 통해 스크립트화할 수 있습니다. 즉석에서 보고서를 읽고 싶을 때는 채팅을 이용해 임시 배치를 수행하면 됩니다.

제한 사항은 무엇인가요?

  • 평가 모드에서는 배치당 15개 문서로 제한됩니다. 라이선스가 없을 경우 하나의 서버 프로세스가 동시에 열 수 있는 문서는 최대 15개이며, 출력물에는 평가 워터마크가 삽입됩니다. 그 이후 호출은 서버가 재시작될 때까지 실패합니다. 실제 배치를 시작하기 전에 get_license_status 로 모드를 확인하거나 “what is the license status of the conversion server?” 라고 물어보세요.
  • Metered 라이선스는 외부 접속이 필요합니다. Metered 키를 사용할 경우 사용량이 GroupDocs 서버에 보고되므로 방화벽이 있는 머신에서는 라이선스 파일을 사용해야 합니다. 문서 내용 자체는 전송되지 않습니다.
  • 스캔은 이미지 그대로 유지됩니다. OCR 기능은 서버에 포함되지 않으므로 이미지 전용 PDF 배치는 텍스트 레이어를 얻지 못합니다.

FAQ

AI를 사용해 폴더 내 모든 DOCX 파일을 PDF로 변환하려면 어떻게 해야 하나요?
스토리지 폴더를 설정한 뒤 에이전트에게 한 문장으로 정확히 요청하면 됩니다. 에이전트는 로컬 서버를 통해 파일을 하나씩 변환하고, 파일이 업로드되지 않습니다.

AI 에이전트가 전체 폴더를 로컬에서 처리할 수 있나요?
네. 에이전트와 변환 서버 모두 사용자의 머신에서 실행되며, 파일은 사용자의 폴더에서 읽고 쓰게 됩니다.

문서 변환 파이프라인을 자동화하는 가장 좋은 방법은?
검토가 필요한 임시 배치는 채팅을 이용하고, 일정에 따라 자동으로 실행되는 파이프라인은 n8n 같은 워크플로우 도구로 동일 서버를 구동하거나 .NET 라이브러리를 스크립트화하십시오.

더 깊이 파고들기