Skip to main content
Glama
watsonx.data MCP Proxy

watsonx.data MCP Proxy

by kyokonishito
NOTE

まだテスト中です!

watsonx.data MCP Proxy

IBM watsonx.data Premium用のMCPプロキシサーバー。IBM watsonx.data remote Model Context Protocol (MCP) serverに接続し、IBM Cloud APIキーからアクセストークンを自動的に取得・更新してリクエストを中継します。

概要

このプロキシサーバーは、IBM watsonx.data Premiumのremote MCP server機能を利用するためのツールです。IBM Cloud IAMトークンの自動管理により、MCPクライアント(IBM BobやClaude Desktopなど)から簡単にwatsonx.dataのデータにアクセスできます。

Related MCP server: MCP OAuth Gateway

特徴

  • 自動トークン更新: IBM Cloud APIキーから自動的にトークンを取得し、期限切れ前に更新

  • MCPプロトコル対応: Model Context Protocol (MCP)に完全対応

  • 6つのツールをサポート: watsonx.dataのすべてのMCPツールに対応

  • エラーハンドリング: 堅牢なエラー処理とリトライロジック

  • ログ機能: 詳細なログでデバッグが容易

サポートされるツール

  1. LIST_DOCUMENT_LIBRARY - ドキュメントライブラリの一覧取得

  2. QUERY_DOCUMENT_LIBRARY - ドキュメントライブラリへのクエリ実行

  3. LIST_DOCUMENT_SET - ドキュメントセットの一覧取得

  4. QUERY_DOCUMENT_SET - ドキュメントセットへのクエリ実行

  5. LIST_DATA_ASSETS - データアセット(テーブル)の一覧取得

  6. QUERY_DATA_ASSETS - データアセットへのクエリ実行

インストール

前提条件

  • Python 3.10以上

  • pipx(推奨)またはpip

  • IBM Cloud APIキー

  • watsonx.data Premiumインスタンス

インストール方法

方法1: pipxでGitHubから直接インストール(推奨)

pipxを使用すると、独立した環境にインストールされ、システムのPython環境を汚染しません。

# pipxがインストールされていない場合
python -m pip install --user pipx
python -m pipx ensurepath

# GitHubから直接インストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# 特定のブランチやタグからインストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git@main
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git@v0.1.0

方法2: pipでGitHubから直接インストール

# GitHubから直接インストール
pip install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# または、ユーザーディレクトリにインストール
pip install --user git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

方法3: ローカル開発用(開発者向け)

# リポジトリをクローン
git clone https://github.com/kyokonishito/watsonx_data_mcp_proxy.git
cd watsonx_data_mcp_proxy

# uvで仮想環境を作成(推奨)
uv venv
source .venv/bin/activate  # Linux/macOS
# または .venv\Scripts\activate  # Windows

# 開発モードでインストール
uv pip install -e ".[dev]"

# または、pipを使用
pip install -e ".[dev]"

インストールの確認

# コマンドが利用可能か確認
watsonx-data-mcp-proxy --help

# または、Pythonモジュールとして実行
python -m watsonx_data_mcp_proxy --help

アンインストール

pipxでインストールした場合

pipx uninstall watsonx-data-mcp-proxy

pipでインストールした場合

pip uninstall watsonx-data-mcp-proxy

ローカル開発環境の場合

# 開発モードでインストールした場合
pip uninstall watsonx-data-mcp-proxy

# または、仮想環境ごと削除
rm -rf .venv

使用方法

IBM Bob (MCP Client)での設定

IBM Bobで使用する場合、.bob/mcp.jsonに設定を追加します。インストール方法に応じて設定が異なります。

方法1: pipxでインストールした場合(推奨)

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

仮想環境のPythonの絶対パスを指定します:

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

例: プロジェクトが/Users/username/watsonx-data-mcp-proxyにある場合:

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/Users/username/watsonx-data-mcp-proxy/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

重要:

  • 環境変数は.bob/mcp.jsonのenvセクションで設定するため、シェルで別途exportする必要はありません

  • ローカル開発環境では、必ず仮想環境のPythonの絶対パスを指定してください

  • pythonやpython3などの相対コマンドは使用しないでください(モジュールが見つからないエラーが発生します)

Claude Desktop (MCP Client)での設定

Claude Desktopで使用する場合、設定ファイルの場所が異なります。

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

方法1: pipxでインストールした場合(推奨)

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

サーバーの起動

IBM BobまたはClaude Desktopを起動すると、自動的にプロキシサーバーが起動します。トークンは自動的に取得・更新されます。

手動でテストする場合(開発時のみ):

export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
python -m watsonx_data_mcp_proxy

設定オプション

トークン更新マージン

デフォルトでは、トークンの有効期限の5分前に自動更新されます。この値はTokenManagerクラスのrefresh_marginパラメータで変更できます。

ログレベル

環境変数LOG_LEVELでログレベルを設定できます:

export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL

開発

テストの実行

# すべてのテストを実行
pytest

# カバレッジレポート付きで実行
pytest --cov=src/watsonx_data_mcp_proxy --cov-report=html

# 特定のテストファイルのみ実行
pytest tests/test_token_manager.py

# 統合テストを実行(実際のwatsonx.dataに接続)
# 環境変数を設定して実行
export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
pytest tests/test_integration.py -v -m integration

# または、uv仮想環境を使用する場合
IBM_CLOUD_API_KEY="your-api-key" WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/" uv run pytest tests/test_integration.py -v -m integration

# LIST_DATA_ASSETSテストを実行する場合(追加の環境変数が必要)
export WATSONX_DATA_CONTAINER_ID="your-container-id"
export WATSONX_DATA_PRESTO_CRN="your-presto-instance-crn"
export WATSONX_DATA_PRESTO_ENGINE_ID="your-presto-engine-id"
pytest tests/test_integration.py::test_list_data_assets -v -s

テストの種類

  1. ユニットテスト (test_token_manager.py, test_server.py)

    • モックを使用した単体テスト

    • 高速で依存関係なし

  2. 統合テスト (test_integration.py)

    • 実際のIBM Cloudとwatsonx.dataに接続

    • 環境変数の設定が必要

プロジェクト構造

mcp_wxd_premium/
├── src/
│   └── watsonx_data_mcp_proxy/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCPサーバー実装
│       └── token_manager.py   # トークン管理
├── tests/
│   ├── test_token_manager.py  # トークン管理のテスト
│   ├── test_server.py         # サーバーのテスト
│   └── test_integration.py    # 統合テスト
├── .bob/
│   └── mcp.json              # IBM Bob設定ファイル
├── pyproject.toml            # プロジェクト設定
└── README.md                 # このファイル

トラブルシューティング

トークン取得エラー

RuntimeError: IBM Cloudトークンの取得に失敗しました

解決方法:

  • IBM Cloud APIキーが正しいか確認

  • APIキーに適切な権限があるか確認

  • ネットワーク接続を確認

watsonx.data接続エラー

RuntimeError: watsonx.dataへのリクエストが失敗しました

解決方法:

  • watsonx.data URLが正しいか確認

  • watsonx.dataインスタンスでMCPサーバー機能が有効化されているか確認

  • トークンに適切な権限があるか確認

レスポンス形式エラー

Invalid response format: 'rows' is not a string []

解決方法:

  • watsonx.dataのMCPサーバーバージョンを確認

  • プロキシサーバーのログを確認してレスポンス内容を調査

ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細はLICENSEファイルを参照してください。

参考資料

Available Tools

6 tools
LIST_DATA_ASSETSC

提供された接続パラメータに基づいてフィルタリングされたPrestoテーブルを返します

Inputs: container_id (required), container_type (required), presto_engine_id (required), presto_instance_crn (required).

LIST_DOCUMENT_LIBRARYB

すべての利用可能なドキュメントライブラリとそのメタデータをリストします

Inputs: no named parameters.

LIST_DOCUMENT_SETC

指定されたドキュメントライブラリ内のすべてのドキュメントセットとそのメタデータをリストします

Inputs: library_id (required).

QUERY_DATA_ASSETSB

選択されたPrestoテーブルに対して自然言語クエリを実行します

Inputs: query (required), tables (required), container_id (required), container_type (required), +2 more.

QUERY_DOCUMENT_LIBRARYC

指定されたドキュメントライブラリに対して自然言語クエリを実行します

Inputs: query (required), library_id (required).

QUERY_DOCUMENT_SETC

指定されたドキュメントセットに対して自然言語クエリを実行します

Inputs: query (required), set_id (required), library_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    The six tools form clear LIST/QUERY pairs for three distinct resource levels: document libraries, document sets, and Presto data assets. Each tool's target and action are unambiguous, and the hierarchical relationship between library and set is explicit.

    Naming Consistency5/5

    All tool names follow a consistent uppercase snake_case VERB_NOUN pattern (LIST_* or QUERY_* followed by the resource). There is no mixing of conventions.

    Tool Count5/5

    Six tools is well-scoped for a query proxy: three resource types each get exactly a list and query operation. No tool feels redundant or missing for the basic query surface.

    Completeness4/5

    The surface covers discovery and natural-language querying for document libraries, document sets, and Presto tables. However, it lacks any create/update/delete or ingestion operations, and there is no direct way to list individual documents within a set, so management workflows would hit gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides secure integration between MCP clients and IBM Data Intelligence services, enabling AI assistants to interact with IBM's data intelligence capabilities for data management and analytics operations.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A transparent proxy server that simplifies authentication by chaining its own OAuth layer with an upstream MCP server's credentials. It manages dual token sets behind a single interface, enabling secure and streamlined access to protected MCP resources.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A proxy server that connects MCP clients to the Zihin.ai platform via HTTP, enabling management of AI agents, LLM models, and configuration templates. It provides tools for agent creation and resources for discovering tenant-specific agents and schema templates.
      113
      358 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a modular MCP server to integrate with IBM Data Intelligence services, enabling secure interaction with data intelligence capabilities via tools and skills.
      378 PyPI
      20
      Apache 2.0