Upstage MCP Server

Upstage MCP 服务

用于 Upstage AI 文档数字化和信息提取功能的模型上下文协议（MCP）服务

概述

Upstage MCP 服务为 AI 助手与 Upstage AI 强大的文档处理 API 提供了可靠的桥梁。此服务使 Claude 等 AI 模型能够轻松提取并构建各种文档类型中的内容，包括 PDF、图像和 Office 文件。该软件包支持多种格式，并可与 Claude Desktop 无缝集成。

主要功能

• 文档数字化： 在保留版面的同时，从文档中提取结构化内容。
• 信息提取： 使用智能、可自定义的架构检索特定数据点。
• 多格式支持： 支持 JPEG、PNG、BMP、PDF、TIFF、HEIC、DOCX、PPTX 和 XLSX。
• Claude Desktop 集成： 轻松连接 Claude 和其他 MCP 客户端。

先决条件

使用此服务前，请确保具备以下条件：

1. Upstage API 密钥： 从 Upstage API 获取 API 密钥。
2. Python 3.10+： 服务要求 Python 版本为 3.10 或更高版本。
3. MCP 服务依赖 Astral UV 运行，请安装

安装与配置

本指南将逐步说明如何设置和配置 upstage-mcp-server

使用 uv（推荐）

使用 uvx 时无需额外安装，因为它会处理执行过程。不过，如果你更希望直接安装软件包：

uv pip install upstage-mcp-server

配置 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 命令（推荐）

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

如果系统未全局提供 uvx，你可能会遇到 Server disconnected 错误。要解决此问题，请运行 which uvx 查找其完整路径，并将上方的 "command": "uvx" 替换为返回的路径。

添加配置后，重启 Claude Desktop 以应用更改。

输出目录

处理结果存储在主目录下：

• 文档解析结果：
  ~/.upstage-mcp-server/outputs/document_parsing/
• 信息提取结果：
  ~/.upstage-mcp-server/outputs/information_extraction/
• 生成的架构：
  ~/.upstage-mcp-server/outputs/information_extraction/schemas/

本地/开发环境设置

按照以下步骤在本地设置并运行项目：

步骤 1：克隆仓库

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

步骤 2：设置 Python 环境

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

步骤 3：配置 Claude Desktop 以进行本地测试

1. 下载 Claude Desktop：
   下载 Claude Desktop

2. 打开并编辑配置：

   • 前往 Claude → Settings → Developer → Edit Config。
   • 使用以下配置编辑 claude_desktop_config.json 文件：

   Windows：

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

   将 C:\\path\\to\\cloned\\upstage-mcp-server 替换为实际的仓库路径。

   macOS/Linux：

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

   替换：

   • 将 /Users/username/.local/bin/uv 替换为 which uv 的输出。
   • 将 /path/to/cloned/upstage-mcp-server 替换为本地克隆仓库的绝对路径。

macOS/Linux 用户提示： 如果出现连接问题，使用 uv 可执行文件的完整路径可以提升可靠性。

配置完成后，重启 Claude Desktop。

可用工具

该服务向 AI 模型提供两个主要工具：

1. 文档解析（parse_document）：

   • **描述：**处理文档并提取内容，同时保留结构。
   • 参数：
     file_path – 要处理的文档路径。
   • 查询示例：
     “你能解析 C:\Users\username\Documents\contract.pdf 处的文档并提供摘要吗？”

2. 信息提取（extract_information）：

   • **描述：**根据预定义或自动生成的架构，从文档中提取结构化信息。
   • 参数：
     file_path – 文档文件路径；
     schema_path（可选）– 包含提取架构的 JSON 文件；
     auto_generate_schema（默认为 true）– 是否自动生成架构。
   • 查询示例：
     “从 C:\Users\username\Documents\invoice.pdf 中提取发票编号、日期和总额。”

以下是按要求整理后的故障排除部分。你可以将以下 Markdown 直接复制并粘贴到 README 中：

故障排除

常见问题

• 缺少 API 密钥：
  请确保已在 claude_desktop_config.json 文件中正确设置 UPSTAGE_API_KEY。请从 Upstage Console 获取有效的 API 密钥。

• 找不到文件：
  请仔细检查文件路径是否正确且可访问。确保文件路径为绝对路径（例如，C:\Users\name\Documents\file.pdf），并且路径中的任何特殊字符都已正确转义。

• 服务无法启动：
  请确认虚拟环境已激活且已安装所有依赖项。此外，请查看 Claude Desktop 日志文件中的错误：

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

• 服务连接问题：
  请重启 Claude Desktop。确保系统 PATH 中已安装并可访问 uvx，如有需要，也可以在配置中使用其绝对路径。

• 处理失败：
  请检查文档是否为受支持的格式（PDF、JPEG、PNG、TIFF 等），文件大小是否小于 50MB，以及页数是否少于 100 页。请使用更简单的文档进行测试，以确认功能正常。

• 文档格式无效：
  请确认文档格式受支持且未损坏。

• 无法连接到 Upstage API：
  请确认网络连接、防火墙设置以及 claude_desktop_config.json 中的配置详情。查看日志以获取更详细的错误信息。

日志文件

排查问题时，请查看以下位置的服务日志：

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

贡献

欢迎贡献！如果你希望改进项目或添加新功能，请 fork 此仓库并提交 pull request。对于重大更改，请先创建 issue，讨论你希望进行的更改。

许可证

本项目采用 MIT 许可证。