MCP

최근 Upstage는 ‘문서 디지털화 및 정보 추출 기능을 위한 MCP’를 개발하였습니다. 이로 인해 Claude와 같은 AI 모델이 PDF, 이미지 및 Office 파일을 포함한 다양한 문서 유형에서 콘텐츠를 손쉽게 추출하고 구조화할 수 있게 되었습니다. 더 자세한 내용은 라이브러리를 참고해 주세요!

Cursor 와 Claude Desktop 을 통해 Upstage의 Document Digitization(문서 디지털화)와 Information Extraction(정보 추출)기능을 사용해 보도록 하겠습니다.

준비사항

총 3가지의 준비 사항이 필요합니다.

• Upstage Console에서 제공하는 API 키가 필요합니다.
• Python 3.10+ 버전이 필요합니다.
• Astral UV가 설치되어야 합니다.

설치방법

Cursor

1. Cursor Settings Mcp Tools 설정

커서 메뉴 중 Preferences 에서 Cursor Settings 를 들어갑니다.

왼쪽의 Tools & Integrations 를 통해 MCP Tools 설정창으로 이동합니다.

이후 Add Custom MCP 를 클릭하시면 mcp.json 으로 이동됩니다.

이처럼 기본 경로는 Users/${username}/.cursor/mcp.json 입니다.

2-1. uvx의 경우

uvx의 경우 간단하게 설정 가능합니다.

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "uvx",
      "args": ["mcp-upstage"],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

만약 에러가 나는 경우, 터미널에서

which uvx

를 입력하신 후 나온 경로를 command쪽에 작성해주시면 됩니다.

해당 명령어가 실행되지 않는 경우, uv가 제대로 설치되어 있는지 확인해 주세요.

아래는 제 경우의 예시입니다.

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "/Users/gimjuho/.local/bin/uvx",
      "args": ["mcp-upstage"],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

2-2. Github Repository Clone의 경우

먼저 리포지토리를 복제한 후 이동합니다.

git clone <https://github.com/UpstageAI/mcp-upstage.git>
cd mcp-upstage

그 후 uv venv를 활성화해 줍니다. 사용하시는 IDE나 로컬 환경에 따라 구성해주시면 됩니다.

아래는 간단한 예시입니다.

# uv가 설치되지 않았다면 설치
pip install uv

# 가상환경 구축
uv venv

# 가상환경 활성화
# Windows의 경우:
# .venv\\Scripts\\activate
# macOS/Linux의 경우:
source .venv/bin/activate

# editable mode로 의존성 설치
uv pip install -e .

이후 mcp.json을 수정해야 합니다.

Windows의 경우

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "${C:\\\\path\\\\to\\\\cloned\\\\mcp-upstage}",
        "python",
        "-m",
        "upstage_mcp.server"
      ],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

macOS/Linux의 경우

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "${path_to_uv_here}",
      "args": [
        "run",
        "--directory",
        "${/path/to/cloned/mcp-upstage}",
        "python",
        "-m",
        "upstage_mcp.server"
      ],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

command 에는 uv의 경로가 들어가야 합니다.

which uv

해당 명령어를 통해 경로를 확인할 수 있습니다.

따로 설정하신 uv 경로가 있다면, 해당 경로를 사용하셔도 무방합니다.

아래는 제 경우의 예시입니다.

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "/Users/gimjuho/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/gimjuho/Desktop/mcp-upstage",
        "python",
        "-m",
        "upstage_mcp.server"
      ],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

성공적으로 설정이 마쳐졌다면, 이를 MCP Tools 에서 확인하실 수 있습니다.

위 사진과 같이 초록불이 들어와 있다면 잘 적용되고 있는 것입니다.

Claude Desktop

1. Claude Desktop config 설정

Claude Desktop을 설치 후 claude_desktop_config.json 을 수정해야 합니다.

해당 파일 경로는 다음과 같습니다.

'/Users/${username}/Library/Application Support/Claude/claude_desktop_config.json'

직접 찾기 어려우시다면, Claude Desktop 설정에서 찾아가실 수 있습니다.

해당 화면에서 사이드바를 열어 주세요.

사이드바 하단의 프로필을 눌러 주세요.

설정을 눌러줍니다.

왼쪽 하단의 개발자 항목을 눌러줍니다.

처음 들어오셨다면 ‘추가된 서버가 없습니다’라는 메시지가 보이실 겁니다.

구성 편집을 눌러주면, claude_desktop_config.json 의 위치를 찾아갈 수 있게 됩니다.

이후 텍스트편집기 등을 사용하여 내부 파일 내용을 변경해 줍니다.

내부 파일 내용은 어떤 환경을 사용하는지에 따라 나뉘게 됩니다.

2-1. uvx의 경우

uvx의 경우 간단하게 설정 가능합니다.

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "uvx",
      "args": ["mcp-upstage"],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

이후 Claude Desktop을 재실행하시면 됩니다.

만약 위 사진처럼 에러가 나는 경우, 터미널에서

which uvx

를 입력하신 후 나온 경로를 command쪽에 작성해주시면 됩니다.

해당 명령어가 실행되지 않는 경우, uv가 제대로 설치되어 있는지 확인해 주세요.

아래는 제 경우의 예시입니다.

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "/Users/gimjuho/.local/bin/uvx",
      "args": ["mcp-upstage"],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

mcp-upstage가 running인지 확인해 주세요(jetbrains는 목록에 없으실 텐데, 정상이니 걱정하지 않으셔도 됩니다).

2-2. Github Repository Clone의 경우

먼저 리포지토리를 복제한 후 이동합니다.

git clone <https://github.com/UpstageAI/mcp-upstage.git>
cd mcp-upstage

그 후 uv venv를 활성화해 줍니다. 사용하시는 IDE나 로컬 환경에 따라 구성해주시면 됩니다.

아래는 간단한 예시입니다.

# uv가 설치되지 않았다면 설치
pip install uv

# 가상환경 구축
uv venv

# 가상환경 활성화
# Windows의 경우:
# .venv\\Scripts\\activate
# macOS/Linux의 경우:
source .venv/bin/activate

# editable mode로 의존성 설치
uv pip install -e .

이후 Cluade Desktop Config를 수정해야 합니다.

Windows의 경우

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "${C:\\\\path\\\\to\\\\cloned\\\\mcp-upstage}",
        "python",
        "-m",
        "upstage_mcp.server"
      ],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

macOS/Linux의 경우

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "${path_to_uv_here}",
      "args": [
        "run",
        "--directory",
        "${/path/to/cloned/mcp-upstage}",
        "python",
        "-m",
        "upstage_mcp.server"
      ],
      "env": {
        "UPSTAGE_API_KEY": "${your_api_key_here}"
      }
    }
  }
}

command 에는 uv의 경로가 들어가야 합니다.

which uv

해당 명령어를 통해 경로를 확인할 수 있습니다.

보편적으로는 /Users/${username}/.local/bin/uv 의 형태입니다.

사용 예시

출력 디렉토리

처리된 결과는 아래의 홈 디렉토리에 저장됩니다.

• Document Parsing(문서 구문 분석): ~/.mcp-upstage/outputs/document_parsing/
• Information Extraction(정보 추출): ~/.mcp-upstage/outputs/information_extraction/
• Generated Schemas(생성된 스키마): ~/.mcp-upstage/outputs/information_extraction/schemas/