使用说明

项目简介

Upstage MCP Server 旨在作为 AI 助手（如 Claude）与 Upstage AI 强大的文档处理 API 之间的桥梁。它使 AI 模型能够无缝地从各种文档类型（包括 PDF、图像和 Office 文件）中提取和结构化内容。通过 MCP 协议，该服务器标准化了 AI 应用访问 Upstage AI 文档处理能力的流程。

主要功能点

文档数字化: 从文档中提取结构化内容，同时保留原始布局。
信息提取: 根据智能模式提取文档中的特定数据点。
多格式支持: 支持 JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, XLSX 等多种文档格式。
Claude Desktop 集成: 可以与 Claude Desktop 和其他 MCP 客户端无缝集成。

安装步骤

克隆仓库

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

安装 uv 包管理器 (如果尚未安装)
```
pip install uv
```

创建并激活虚拟环境

uv venv
# 激活虚拟环境 (根据你的操作系统选择命令)
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate

安装项目依赖
```
uv pip install -e .
```

服务器配置

要将此 MCP 服务器与 Claude Desktop 等 MCP 客户端集成，您需要配置客户端以连接到此服务器。以下是 Claude Desktop 的配置示例，您需要编辑 'claude_desktop_config.json' 文件，通常位于 Claude 的设置中（Developer -> Edit Config）。

在 'claude_desktop_config.json' 文件中，添加或修改 'mcpServers' 部分，加入以下配置：

{
  "mcpServers": {
    "upstage-mcp-server": {  // 服务器名称，在Claude Desktop中用于标识
      "command": "uv",      // 启动服务器的命令，这里使用 uv 包管理器
      "args": [             // 启动命令的参数列表
        "run",               // uv run 命令用于运行 Python 模块
        "--directory",       // 指定工作目录
        "/path/to/cloned/upstage-mcp-server", // 替换为克隆仓库的绝对路径
        "python",            // 使用 python 解释器
        "-m",                // 运行模块
        "upstage_mcp.server" // 指定要运行的 Python 模块，即服务器入口
      ],
      "env": {              // 环境变量
        "UPSTAGE_API_KEY": "your_api_key_here" // 替换为您的 Upstage API 密钥
      }
    }
  }
}

配置参数说明:

'"upstage-mcp-server"': 服务器的唯一名称，Claude Desktop 使用此名称来引用此服务器。您可以自定义此名称。
'"command": "uv"': 指定用于启动服务器的命令。这里假设您使用 'uv' 包管理器，并且 'uv' 命令在您的系统 PATH 中可用。如果 'uv' 不在 PATH 中，您需要提供 'uv' 可执行文件的完整路径。
'"args": [...]': 启动命令的参数列表。
- '"run"': 'uv run' 命令指示 'uv' 运行一个 Python 模块或脚本。
- '"--directory", "/path/to/cloned/upstage-mcp-server"': 指定服务器的工作目录为克隆仓库的根目录。请务必将 '"/path/to/cloned/upstage-mcp-server"' 替换为您实际克隆仓库的绝对路径。
- '"python", "-m", "upstage_mcp.server"': 指示使用 Python 解释器运行 'upstage_mcp.server' 模块。这是服务器的入口点。
'"env": { "UPSTAGE_API_KEY": "your_api_key_here" }': 设置服务器运行所需的环境变量。
- '"UPSTAGE_API_KEY": "your_api_key_here"': 您必须将 '"your_api_key_here"' 替换为您从 Upstage AI 平台获取的 API 密钥。 这是服务器连接 Upstage AI 服务的凭证。

配置完成后，请重启 Claude Desktop 使配置生效。

基本使用方法

配置完成后，您可以在 Claude Desktop 中通过自然语言指令调用 Upstage MCP Server 提供的工具。

1. 文档解析 ('parse_document' 工具)

向 Claude 提问，要求解析指定路径的文档并总结内容。例如：

Can you parse this document located at "C:\Users\username\Documents\contract.pdf" and summarize its contents?

服务器会将文档解析为结构化内容，并返回 JSON 格式的文本内容。完整响应会保存到 'upstage_mcp/outputs/document_parsing/' 目录下。

2. 信息提取 ('extract_information' 工具)

向 Claude 提问，要求从指定路径的文档中提取特定信息。例如：

Extract the invoice number, date, and total amount from this document at "C:\Users\username\Documents\invoice.pdf".

服务器会尝试根据文档内容自动生成 Schema 并提取信息，或者您也可以提供 Schema 文件路径或 JSON 字符串。提取结果将以 JSON 格式返回，完整响应和生成的 Schema (如果自动生成) 会保存到 'upstage_mcp/outputs/information_extraction/' 目录下。

注意: 文件路径需要是服务器可以访问的路径。对于 Claude Desktop 等客户端，路径通常需要是服务器运行的本地文件系统路径。

故障排除

如果遇到问题，请检查以下事项：

API 密钥: 确保 'UPSTAGE_API_KEY' 环境变量已正确设置。
文件路径: 确认文件路径正确且服务器可以访问。
依赖安装: 确保虚拟环境已激活并且所有依赖已安装。
日志: 查看 Claude Desktop 的日志文件 ('%APPDATA%\Claude\logs\mcp-server-upstage-mcp-server.log' (Windows) 或 '~/Library/Logs/Claude/mcp-server-upstage-mcp-server.log' (macOS)) 以获取错误信息。

关键词