Upstage MCP 服务器

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

概述

Upstage MCP 服务器在 AI 助手和 Upstage AI 强大的文档处理 API 之间提供了一个强大的桥梁。该服务器使 AI 模型（如 Claude）能够轻松地从各种文档类型（包括 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 环境

# 如果尚未安装，请安装 uv
pip install uv

# 创建并激活虚拟环境
uv venv

# 激活虚拟环境
# 在 Windows 上：
# .venv\Scripts\activate
# 在 macOS/Linux 上：
source .venv/bin/activate

# 以可编辑模式安装依赖项
uv pip install -e .

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

1. 下载 Claude Desktop： 下载 Claude Desktop

2. 打开并编辑配置：

   • 导航到 Claude → 设置 → 开发者 → 编辑配置。
   • 使用以下配置编辑 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 密钥： 确保您的 UPSTAGE_API_KEY 在您的 claude_desktop_config.json 文件中正确设置。从 Upstage 控制台 获取有效的 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。确保 uvx 已安装并且在您的系统 PATH 中可用，或者如果需要，请在其配置中使用其绝对路径。

• 处理失败： 检查文档是否为支持的格式（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 许可证获得许可。