Upstage MCP Server는 AI 어시스턴트와 업스테이지 AI의 강력한 문서 처리 API 사이를 견고하게 이어주는 브리지를 제공해요. 이 서버를 통해 Claude와 같은 AI 모델이 PDF, 이미지, Office 파일 등 다양한 문서 유형에서 콘텐츠를 손쉽게 추출하고 구조화할 수 있어요.
주요 기능
- Document Parsing: 레이아웃을 보존하면서 문서에서 구조화된 콘텐츠를 추출해요
- Information Extraction: 지능적이고 커스터마이즈 가능한 스키마를 사용해 특정 데이터 포인트를 가져와요
- 다중 포맷 지원: JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX 형식을 지원해요
- Claude Desktop 연동: Claude 및 다른 MCP 클라이언트와 손쉽게 통합돼요
사전 준비 사항
이 서버를 사용하기 전에 다음 항목을 준비해주세요.
- Upstage API 키: Upstage Console에서 API 키를 발급받아 주세요
- Python 3.10+: 서버 실행을 위해 Python 3.10 이상이 필요해요
- Astral UV: MCP 서버는 Astral UV에 의존하여 실행돼요. UV 설치 페이지를 참고해 설치해주세요
설치 및 설정
Claude Desktop 설정
Claude Desktop과 연동하려면 claude_desktop_config.json 파일에 다음 내용을 추가해주세요.
설정 파일 위치:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
uvx 명령어 사용 (권장):
uvx가 전역에서 사용 가능하지 않은 경우 Server disconnected 오류가 발생할 수 있어요. 이를 해결하려면 which uvx로 전체 경로를 확인한 뒤, 위 설정의 "command": "uvx"를 반환된 경로로 교체해주세요.
설정을 추가한 뒤 Claude Desktop을 재시작하면 변경 사항이 적용돼요.
결과물 저장 디렉터리
처리 결과는 사용자의 홈 디렉터리 아래에 저장돼요.
- Document Parsing 결과:
~/.mcp-upstage/outputs/document_parsing/ - Information Extraction 결과:
~/.mcp-upstage/outputs/information_extraction/ - 생성된 스키마:
~/.mcp-upstage/outputs/information_extraction/schemas/
로컬 개발 환경 설정
프로젝트를 로컬에서 설정하고 실행하려면 다음 단계를 따라주세요.
로컬 테스트를 위한 Claude Desktop 설정
-
Claude Desktop 다운로드: Claude Desktop 다운로드
-
설정 열기 및 편집:
- Claude → Settings → Developer → Edit Config로 이동해요
claude_desktop_config.json파일을 아래 설정으로 편집해요
Windows 용:
C:\\path\\to\\cloned\\mcp-upstage를 실제 레포지토리 경로로 변경해주세요.macOS/Linux 용:
다음 값을 교체해주세요.
/Users/username/.local/bin/uv는which uv결과로 교체/path/to/cloned/mcp-upstage는 로컬 클론의 절대 경로로 교체
설정을 마친 뒤 Claude Desktop을 재시작해주세요.
제공되는 도구
서버는 AI 모델이 사용할 수 있는 두 가지 주요 도구를 제공해요.
Document Parsing (parse_document)
- 설명: 문서의 구조를 보존하면서 콘텐츠를 처리하고 추출해요
- 파라미터:
file_path– 처리할 문서의 경로output_formats(선택) – 반환할 출력 형식 (예:html,text,markdown)mode(기본값standard) – 파싱 모드.standard는 일반적인 텍스트 중심 문서를 빠르고 저렴하게 처리해요.enhanced는 복잡한 표, 차트, 손글씨, 저화질 스캔 문서에 적합하며 페이지당 비용이 더 들고 처리 속도가 느려요.auto는 페이지마다 고급 처리가 필요한지 API가 판단해요ocr(기본값force) – OCR 모드.force는 항상 OCR을 실행하고,auto는 디지털 문서에 포함된 텍스트를 사용하며 필요할 때만 OCR을 실행해요model(기본값document-parse) – Document Parse 모델 이름. 기본값document-parse는 최신 버전을 사용하며,document-parse-260930처럼 날짜가 붙은 버전을 지정하면 버전을 고정할 수 있어요
- 참고: 응답 끝에
Processed by <model> | usage: {...}줄이 붙으며, 실제로 적용된 모델과 모드를 확인할 수 있어요 - 예시 쿼리: "Can you parse the document at
C:\Users\username\Documents\contract.pdfand provide a summary?"
Information Extraction (extract_information)
- 설명: 사전 정의되었거나 자동으로 생성된 스키마를 기반으로 문서에서 구조화된 정보를 추출해요
- 파라미터:
file_path– 문서 파일 경로schema_path(선택) – 추출 스키마를 담은 JSON 파일schema_json(선택) – JSON 문자열로 전달하는 추출 스키마auto_generate_schema(기본값 true) – 스키마 자동 생성 여부
- 예시 쿼리: "Extract the invoice number, date, and total from
C:\Users\username\Documents\invoice.pdf."
문제 해결
문제 해결을 위해 다음 위치의 서버 로그를 확인해주세요.
- Windows:
%APPDATA%\Claude\logs\mcp-upstage.log - macOS:
~/Library/Logs/Claude/mcp-upstage.log