Upstage MCP Server

Upstage MCP Server

Upstage AI のドキュメントデジタル化および情報抽出機能を提供する Model Context Protocol（MCP）サーバー

概要

Upstage MCP Server は、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 モデル向けに次の 2 つの主要なツールを公開しています。

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 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 を再起動してください。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

貢献

貢献を歓迎します。このプロジェクトの改善や新機能の追加を希望する場合は、リポジトリをフォークしてプルリクエストを送信してください。大規模な変更の場合は、まず課題を作成して、変更したい内容について話し合ってください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。