> For the complete documentation index, see [/llms.txt](/llms.txt).

> Source: /docs/guides/mcp-server

# 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](https://console.upstage.ai/api-keys)
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](https://docs.astral.sh/uv/getting-started/installation/)

## Installation & Configuration

### Install the package

Using `uv` (Recommended):

```bash
uv pip install mcp-upstage
```

No additional installation is required when using `uvx` as it handles execution automatically.

### Configure Claude Desktop

For integration with Claude Desktop, add the following content to your `claude_desktop_config.json`:

**Configuration Location:**

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Using uvx Command (Recommended):**

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

If `uvx` is not available globally, you may encounter a `Server disconnected` error. To resolve this, run `which uvx` to find its full path, and replace `"command": "uvx"` above with the returned path.

After adding the configuration, restart Claude Desktop to apply the changes.

## 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:

### Clone the Repository

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

### Set Up the Python Environment

```bash
# 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 .
```

### Configure Claude Desktop for Local Testing

1. **Download Claude Desktop:** [Download Claude Desktop](https://claude.ai/download)

2. **Open and Edit Configuration:**

   - Navigate to **Claude → Settings → Developer → Edit Config**
   - Edit the `claude_desktop_config.json` file with the following configurations:

   **For Windows:**

   ```json
   {
     "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"
         }
       }
     }
   }
   ```

   Replace `C:\\path\\to\\cloned\\mcp-upstage` with your actual repository path.

   **For macOS/Linux:**

   ```json
   {
     "mcpServers": {
       "mcp-upstage": {
         "command": "/Users/username/.local/bin/uv",
         "args": [
           "run",
           "--directory",
           "/path/to/cloned/mcp-upstage",
           "python",
           "-m",
           "upstage_mcp.server"
         ],
         "env": {
           "UPSTAGE_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

   Replace:

   - `/Users/username/.local/bin/uv` with the output of `which uv`
   - `/path/to/cloned/mcp-upstage` with the absolute path to your local clone

After configuring, restart Claude Desktop.

## 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`

### API Key Missing

Ensure that your UPSTAGE\_API\_KEY is correctly set in your `claude_desktop_config.json` file. Obtain a valid API key from [Upstage Console](https://console.upstage.ai/api-keys).

### File Not Found

Double-check the file path for correctness and accessibility. Ensure that file paths are absolute (e.g., `C:\Users\name\Documents\file.pdf`) and that any special characters in the path are properly escaped.

### Server Not Starting

Verify that your virtual environment is activated and all dependencies are installed. Additionally, review the Claude Desktop log files for errors:

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

### Server Connection Issues

Restart Claude Desktop. Ensure that `uvx` is installed and available in your system PATH, or use its absolute path in your configuration if needed.

### Processing Failures

Check that the document is in a supported format (PDF, JPEG, PNG, TIFF, etc.), its file size is under 50MB, and it contains fewer than 100 pages. Test with a simpler document to confirm functionality.

### Failed to Connect to Upstage API

Confirm your network connection, firewall settings, and configuration details in `claude_desktop_config.json`. Review the logs for more detailed error messages.