MinerU Open MCP

MinerU의 문서 파싱 기능을 MCP 도구로 제공하는 공식 MinerU MCP 서버입니다. MCP 호환 AI 클라이언트를 연결하여 PDF, Word 문서, PowerPoint 파일 및 이미지를 마크다운으로 변환하세요.

API 키가 필요하지 않습니다 — Flash 모드는 별도의 가입 없이 즉시 사용할 수 있으며, 최대 20페이지/10MB까지 무료로 제공됩니다. 더 높은 제한과 추가 출력 형식을 사용하려면 MINERU_API_TOKEN을 설정하세요.

⚡ 가장 빠른 실행 방법 — uvx (설치 불필요)

mineru-open-mcp는 PyPI에 등록되어 있습니다. uv가 설치되어 있다면 별도의 설치 단계 없이 바로 실행할 수 있습니다.

MCP 클라이언트 구성

stdio — Claude Desktop, Cursor, Windsurf

MCP 클라이언트가 mineru-open-mcp를 하위 프로세스로 자동 실행합니다.

uvx 사용 (권장 — 항상 최신 버전 실행):

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["mineru-open-mcp"],
      "env": {
        "MINERU_API_TOKEN": "your_key_here"
      }
    }
  }
}

API 키가 없나요? 서버는 Flash 모드로 실행됩니다. 무료이며 마크다운 출력만 지원합니다. 자세한 내용은 Flash 모드 문서를 참조하세요.

mineru-open-mcp가 PATH에 없나요? 전체 경로를 사용하세요: "/Users/you/.local/bin/mineru-open-mcp", 또는 위에서 언급한 uvx 방식을 사용하면 자동으로 처리됩니다.

사용 예시

예시 1: 대상 페이지 범위를 지정하여 로컬 PDF 문서 파싱

사용자 프롬프트: "이 PDF의 3~5페이지를 마크다운으로 파싱해줘: <파일_경로>" 작동 방식:

MinerU가 PDF를 업로드하고 파싱합니다.
표(HTML)와 수식(Latex)이 보존된 깔끔한 마크다운을 반환합니다.
길이가 허용되는 경우 채팅창에 마크다운 텍스트와 출력 경로를 반환하며, 원할 경우 zip URL도 제공합니다.
MCP 클라이언트가 내용을 요약합니다.

예시 2: 파일이 호스팅된 원격 URL 파싱

사용자 프롬프트: "이 논문의 내용을 추출해줘: https://arxiv.org/pdf/2509.22186" 작동 방식:

MinerU가 논문을 마크다운으로 파싱합니다.
MCP 클라이언트가 표를 형식에 맞게 정리하고 설명합니다.

예시 3: 독립적인 페이지 범위를 지정하여 로컬 PDF 파일 파싱

사용자 프롬프트: "<파일1> 1-5페이지, <파일2> 2-9페이지, <파일3> 3페이지를 마크다운으로 파싱해줘" 작동 방식:

MinerU가 각 파일을 개별적으로 업로드하고 파싱합니다.
대상 형식의 출력물, 다운로드 가능한 zip URL, 마크다운 요약본, 저장할 디렉토리 경로를 반환합니다.
MCP 클라이언트가 추가 분석을 위해 내용을 사용합니다.

예시 4: 고급 사용자 설정

사용자 프롬프트1: "파이프라인 모델을 사용하여 이 한국어 파일을 파싱해줘: 파일_경로" 사용자 프롬프트2: "파일_경로를 파싱해서 마크다운을 출력_디렉토리_경로에 저장해줘" 작동 방식:

파이프라인 모델은 MinerU 서비스에서 제공하는 또 다른 모델입니다 (참고: 기본값은 vlm 모델입니다).
프롬프트를 구성하여 모델, OCR 언어, 또는 OUTPUT_DIR과 다른 독립적인 출력 디렉토리를 지정할 수 있습니다.
요청은 parse_documents 도구의 매개변수로 변환되며 MinerU가 나머지를 처리합니다.

streamable-http — 웹 기반 MCP 클라이언트

서버를 수동으로 시작한 다음 클라이언트를 연결하세요:

MINERU_API_TOKEN=your_key mineru-open-mcp --transport streamable-http --port 8001

{
  "mcpServers": {
    "mineru": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

기능

parse_documents — 로컬 파일 및/또는 원격 URL을 마크다운으로 변환합니다. 입력 지원 형식: PDF, 이미지(png/jpg/jpeg/jp2/webp/gif/bmp), Doc, Docx, Ppt, PPTx. Flash 모드는 xlsx도 지원합니다.
get_ocr_languages — MinerU에서 지원하는 모든 OCR 언어 목록을 나열합니다.
Flash 모드 — API 키 없이 작동합니다 (무료, 마크다운 출력만 가능, PDF/이미지/Docx/PPTx/xls/xlsx 지원). 모든 기능을 사용하려면 MINERU_API_TOKEN을 제공하세요. 토큰 제공 시 Flash 모드는 비활성화됩니다.
출력 동작 — 단일 파일 파싱은 기본적으로 인라인 마크다운을 반환합니다. 배치 파싱은 결과를 디스크에 저장하고 파일 메타데이터를 반환합니다. 크기가 큰 인라인 콘텐츠는 로컬에 저장되고 extract_path를 통해 반환됩니다.
두 가지 전송 모드 — stdio, streamable-http

환경 변수

변수	설명	기본값
`MINERU_API_TOKEN`	MinerU API 토큰. 모든 기능을 사용하려면 MinerU에서 신청하세요. 제공되지 않으면 Flash 모드가 활성화됩니다.	—
`OUTPUT_DIR`	배치 파싱이나 크기가 큰 인라인 콘텐츠 등 파싱 결과를 로컬에 저장해야 할 때 사용하는 디렉토리	`~/mineru-downloads`

개인정보 처리방침

mineru-open-mcp는 문서 파싱을 위해 공식 MinerU API(mineru.net)에 연결합니다.

전송 데이터: 문서 내용 (파싱을 위해 제공하는 파일 또는 URL)
데이터 저장: 파싱된 결과는 MinerU 서버에 일시적으로 캐시되며, 학습에는 사용되지 않습니다.
제3자: MinerU API (mineru.net) — MinerU 개인정보 처리방침 참조
로컬 데이터: 파싱된 결과는 대상 출력 디렉토리에 저장됩니다. 로그 파일(ENABLE_LOG=true인 경우에만)은 MINERU_LOG_DIR에 저장됩니다.
문의: OpenDataLab@pjlab.org.cn (또는 MinerU-Ecosystem에 이슈 제기)

MinerU Open MCP (Official)