Upstage MCP Server

The Upstage MCP Server provides a robust bridge between AI assistants and Upstage AI's powerful document processing APIs. This server enables AI models—such as Claude—to effortlessly extract and structure content from various document types including PDFs, images, and Office files.

Key Features

• Document Parsing: Extract structured content from documents while preserving layout
• Information Extraction: Retrieve specific data points using intelligent, customizable schemas
• Multi-format Support: Handles JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, and XLSX
• Claude Desktop Integration: Effortless integration with Claude and other MCP clients

Prerequisites

Before using this server, ensure you have the following:

1. Upstage API Key: Obtain your API key from Upstage Console
2. Python 3.10+: The server requires Python version 3.10 or higher
3. Astral UV: The MCP server relies upon Astral UV to run, please install UV

Installation & Configuration

uv pip install mcp-upstage

{
  "mcpServers": {
    "mcp-upstage": {
      "command": "uvx",
      "args": ["mcp-upstage"],
      "env": {
        "UPSTAGE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Output Directories

Processing results are stored in your home directory under:

• Document Parsing Results: ~/.mcp-upstage/outputs/document_parsing/
• Information Extraction Results: ~/.mcp-upstage/outputs/information_extraction/
• Generated Schemas: ~/.mcp-upstage/outputs/information_extraction/schemas/

Local Development Setup

Follow these steps to set up and run the project locally:

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

# Install uv if not already installed
pip install uv

# Create and activate a virtual environment
uv venv

# Activate the virtual environment
# On Windows:
# .venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies in editable mode
uv pip install -e .

Available Tools

The server exposes two primary tools for AI models:

Document Parsing (parse_document)

• Description: Processes documents and extracts content while preserving structure
• Parameters:
  • file_path – the path to the document to be processed
  • output_formats (optional) – output formats to return (e.g., html, text, markdown)
  • mode (default standard) – parsing mode. standard is fast and cost-efficient for ordinary text-centric documents. enhanced is for complex tables, charts, handwriting, or low-quality scans; it costs more per page and is slower. auto lets the API decide per page whether enhanced processing is needed
  • ocr (default force) – OCR mode. force always runs OCR; auto uses the embedded text of digital documents and runs OCR only when needed
  • model (default document-parse) – Document Parse model name. The default document-parse uses the latest version; specify a dated version such as document-parse-260930 to pin it
• Note: The response ends with a Processed by <model> | usage: {...} line showing the model and the mode actually applied
• Example Query: "Can you parse the document at C:\Users\username\Documents\contract.pdf and provide a summary?"

Information Extraction (extract_information)

• Description: Extracts structured information from documents based on predefined or auto-generated schemas
• Parameters:
  • file_path – the document file path
  • schema_path (optional) – a JSON file with an extraction schema
  • schema_json (optional) – an extraction schema as a JSON string
  • auto_generate_schema (default true) – whether to auto-generate a schema
• Example Query: "Extract the invoice number, date, and total from C:\Users\username\Documents\invoice.pdf."

Troubleshooting

For troubleshooting, view the server logs at:

• Windows: %APPDATA%\Claude\logs\mcp-upstage.log
• macOS: ~/Library/Logs/Claude/mcp-upstage.log