概要
Instana MCP Serverは、IBM BobのModel Context Protocol (MCP)を通じてInstanaの監視機能にアクセスするためのサーバーです。このガイドでは、IBM Bobでの5つの異なるインストール方法について詳細に説明します。
IBM Bobでの設定方法
IBM Bobでは、2つの設定方法があります:
方法A: GUI設定(推奨)
IBM BobのSettings画面から直接設定する方法
方法B: 設定ファイル編集
mcp_settings.jsonファイルを直接編集する方法
インストール方式一覧
- UVX (Stdio Mode - Pinned Version) - 推奨
- UVX (Stdio Mode - Latest Version)
- NPX (Streamable HTTP Mode)
- Docker (Stdio Mode - Pinned Version)
- Docker (Stdio Mode - Latest Version)
前提条件
すべてのインストール方法に共通する前提条件:
- Instana API Token: Instanaインスタンスから取得したAPIトークン
-
Instana Base URL: InstanaインスタンスのURL(例:
https://your-instana-instance.instana.io)
方法1: UVX (Stdio Mode - Pinned Version) 【推奨】
概要
UVXを使用してPyPIから固定バージョンをインストールする最も簡単で推奨される方法です。
特徴
- 最も簡単なインストール方法
- バージョン固定で安定性が高い
- 環境変数で認証情報を管理
- Stdio通信モード(標準入出力)
インストール手順
ステップ1: UVのインストール
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
ステップ2: IBM Bobでの設定
方法A: GUI設定(推奨)
- IBM Bobを起動
- Settings → MCP を開く
- Search MCP Servers で「instana」を検索
- Instana を選択し、設定画面を開く
- 以下の項目を設定:
- Installation Scope: Global または Project を選択
-
Installation Method:
UVX (Stdio Mode - Pinned Version)を選択 -
Instana Base URL:
https://your-instana-instance.instana.io -
Instana API Token:
your_instana_api_token -
MCP Instana Version:
0.7.1
(最新バージョンの確認: CHANGELOG.md)
- Update ボタンをクリック
注意: GUI設定を使用する場合、環境変数の設定は不要です。GUI画面で入力したInstana Base URLとAPI Tokenが自動的に設定ファイルに保存されます。
方法B: 設定ファイル編集(環境変数を使用する場合)
設定ファイルを直接編集する場合のみ、環境変数を使用できます。
まず環境変数を設定:
# Bash/Zsh
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"
# Windows (PowerShell)
$env:INSTANA_BASE_URL="https://your-instana-instance.instana.io"
$env:INSTANA_API_TOKEN="your_instana_api_token"
次に設定ファイルを編集:
macOS: ~/.bob/settings/mcp_settings.json
Windows: %USERPROFILE%\.bob\settings\mcp_settings.json
Linux: ~/.bob/settings/mcp_settings.json
例:
{
"mcpServers": {
"instana": {
"command": "uvx",
"args": [
"mcp-instana==0.8.0",
"--transport",
"stdio"
],
"env": {
"INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
"INSTANA_API_TOKEN": "your_instana_api_token"
}
}
}
}
ステップ3: IBM Bobの再起動
設定完了後、IBM Bobを再起動してください。
ステップ4: 接続確認
IBM Bobを開き、MCPセクションでInstana MCPサーバーが「Installed / Global」または「Installed / Project」として表示されていることを確認します。
方法2: UVX (Stdio Mode - Latest Version)
概要
常に最新バージョンを使用したい場合の方法です。
特徴
- ✅常に最新機能を利用可能
- ⚠️ バージョン更新による互換性問題の可能性
- ✅ 環境変数で認証情報を管理
- ✅ Stdio通信モード
インストール手順
ステップ1: 方法1と同じ
UVのインストールは方法1と同じです。
ステップ2: IBM Bobでの設定
方法A: GUI設定(推奨)
- IBM Bobを起動
- Settings → MCP を開く
- Search MCP Servers で「instana」を検索
- Instana を選択し、設定画面を開く
- 以下の項目を設定:
- Installation Scope: Global または Project を選択
-
Installation Method:
UVX (Stdio Mode - Latest Version)を選択 -
Instana Base URL:
https://your-instana-instance.instana.io -
Instana API Token:
your_instana_api_token
- Update ボタンをクリック
方法B: 設定ファイル編集
{
"mcpServers": {
"instana": {
"command": "uvx",
"args": [
"--refresh",
"mcp-instana",
"--transport",
"stdio"
],
"env": {
"INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
"INSTANA_API_TOKEN": "your_instana_api_token"
}
}
}
}
注意:
-
--refreshフラグにより、起動時に最新バージョンをチェックします - GUI設定を使用する場合、環境変数の設定は不要です
ステップ3〜4: 方法1と同じ
方法3: NPX (Streamable HTTP Mode)
概要
NPXを使用してStreamable HTTPモードで実行する方法です。
特徴
- ✅ HTTPヘッダーで認証(環境変数不要)
- ✅ 異なるリクエストごとに異なる認証情報を使用可能
- ✅ 共有環境に適している
- ⚠️ Node.jsが必要
インストール手順
ステップ1: Node.jsのインストール
# macOS (Homebrew)
brew install node
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm
# Windows
# https://nodejs.org/ からインストーラーをダウンロード
ステップ2: MCPサーバーの起動
# デフォルトポート8080で起動
npx mcp-instana --transport streamable-http
# カスタムポートで起動
npx mcp-instana --transport streamable-http --port 9000
# デバッグモード
npx mcp-instana --transport streamable-http --log-level DEBUG
# 特定のツールカテゴリのみ有効化
npx mcp-instana --transport streamable-http --tools infra,events
ステップ3: IBM Bobでの設定
方法A: GUI設定(推奨)
- IBM Bobを起動
- Settings → MCP を開く
- Search MCP Servers で「instana」を検索
- Instana を選択し、設定画面を開く
- 以下の項目を設定:
- Installation Scope: Global または Project を選択
-
Installation Method:
NPX (Streamable HTTP Mode)を選択 -
Instana Base URL:
https://your-instana-instance.instana.io -
Instana API Token:
your_instana_api_token
- Update ボタンをクリック
注意: GUI設定を使用する場合、環境変数の設定は不要です。
方法B: 設定ファイル編集
{
"mcpServers": {
"instana": {
"command": "npx",
"args": [
"mcp-remote",
"http://0.0.0.0:8080/mcp/",
"--allow-http",
"--header",
"instana-base-url: https://your-instana-instance.instana.io",
"--header",
"instana-api-token: your_instana_api_token"
]
}
}
}
ステップ4: サーバーの確認
# サーバーヘルスチェック
curl http://0.0.0.0:8080/mcp/
# カスタムポートの場合
curl http://0.0.0.0:9000/mcp/
ステップ5: IBM Bobの再起動(この方法だと再起動しなくても反映されますが、念のため)
方法4: Docker (Stdio Mode - Pinned Version)
概要
Dockerコンテナを使用して固定バージョンを実行する方法です。
特徴
- ✅ 環境の分離と再現性
- ✅ バージョン固定で安定性が高い
- ✅ 複数環境での一貫性
- ⚠️ Dockerが必要
インストール手順
ステップ1: Dockerのインストール
# macOS
brew install --cask docker
# Ubuntu/Debian
sudo apt update
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
# Windows
# https://www.docker.com/products/docker-desktop からインストール
ステップ2: Dockerイメージのビルド
プロジェクトのルートディレクトリで:
# リポジトリのクローン
git clone https://github.com/instana/mcp-instana.git
cd mcp-instana
# Dockerイメージのビルド
docker build -t mcp-instana:pinned -f Dockerfile .
ステップ3: IBM Bobでの設定
方法A: GUI設定(推奨)
- IBM Bobを起動
- Settings → MCP を開く
- Search MCP Servers で「instana」を検索
- Instana を選択し、設定画面を開く
- 以下の項目を設定:
- Installation Scope: Global または Project を選択
-
Installation Method:
Docker (Stdio Mode - Pinned Version)を選択 -
Instana Base URL:
https://your-instana-instance.instana.io -
Instana API Token:
your_instana_api_token
- Update ボタンをクリック
注意: GUI設定を使用する場合、環境変数の設定は不要です。
方法B: 設定ファイル編集
{
"mcpServers": {
"instana": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--env",
"INSTANA_BASE_URL=https://your-instana-instance.instana.io",
"--env",
"INSTANA_API_TOKEN=your_instana_api_token",
"mcp-instana:pinned"
]
}
}
}
ステップ4: IBM Bobの再起動
方法5: Docker (Stdio Mode - Latest Version)
概要
Dockerコンテナを使用して常に最新バージョンを実行する方法です。
特徴
- ✅ 環境の分離と再現性
- ✅ 常に最新機能を利用可能
- ⚠️ バージョン更新による互換性問題の可能性
- ⚠️ Dockerが必要
インストール手順
ステップ1: Dockerのインストール
方法4と同じです。
ステップ2: Dockerイメージのビルド
# リポジトリのクローン
git clone https://github.com/instana/mcp-instana.git
cd mcp-instana
# 最新版用のDockerイメージのビルド
docker build -t mcp-instana:latest -f Dockerfile .
ステップ3: IBM Bobでの設定
方法A: GUI設定(推奨)
- IBM Bobを起動
- Settings → MCP を開く
- Search MCP Servers で「instana」を検索
- Instana を選択し、設定画面を開く
- 以下の項目を設定:
- Installation Scope: Global または Project を選択
-
Installation Method:
Docker (Stdio Mode - Latest Version)を選択 -
Instana Base URL:
https://your-instana-instance.instana.io -
Instana API Token:
your_instana_api_token
- Update ボタンをクリック
注意: GUI設定を使用する場合、環境変数の設定は不要です。
方法B: 設定ファイル編集
{
"mcpServers": {
"instana": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--pull",
"always",
"--env",
"INSTANA_BASE_URL=https://your-instana-instance.instana.io",
"--env",
"INSTANA_API_TOKEN=your_instana_api_token",
"mcp-instana:latest"
]
}
}
}
注意: --pull alwaysフラグにより、起動時に最新イメージをプルします。
ステップ4: IBM Bobの再起動
開発者向けインストール(ローカル開発)
概要
ソースコードから直接実行する開発者向けの方法です。
インストール手順
ステップ1: リポジトリのクローン
git clone https://github.com/instana/mcp-instana.git
cd mcp-instana
ステップ2: UVのインストールと依存関係の解決
# UVのインストール(まだの場合)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 依存関係の同期
uv sync
ステップ3: 環境変数の設定
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"
ステップ4: サーバーの起動
Stdio Mode(デフォルト):
# 基本起動
uv run src/core/server.py
# 明示的にStdioモード指定
uv run src/core/server.py --transport stdio
# デバッグモード
uv run src/core/server.py --transport stdio --debug
Streamable HTTP Mode:
# デフォルトポート8080
uv run src/core/server.py --transport streamable-http
# カスタムポート
uv run src/core/server.py --transport streamable-http --port 9000
# 特定ツールのみ有効化
uv run src/core/server.py --transport streamable-http --tools infra,app,events
ステップ5: IBM Bobでの設定(Stdio Mode)
設定ファイル編集
{
"mcpServers": {
"instana": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-instana",
"run",
"src/core/server.py",
"--transport",
"stdio"
],
"env": {
"INSTANA_BASE_URL": "https://your-instana-instance.instana.io",
"INSTANA_API_TOKEN": "your_instana_api_token"
}
}
}
}
各インストール方法の比較
| 方法 | 通信モード | バージョン管理 | 認証方式 | 難易度 | 推奨用途 |
|---|---|---|---|---|---|
| 方法1: UVX Pinned | Stdio | 固定 | 環境変数 | ⭐ 簡単 | 本番環境(推奨) |
| 方法2: UVX Latest | Stdio | 最新 | 環境変数 | ⭐ 簡単 | 最新機能テスト |
| 方法3: NPX HTTP | HTTP | 最新 | HTTPヘッダー | ⭐⭐ 中級 | 共有環境・複数認証 |
| 方法4: Docker Pinned | Stdio | 固定 | 環境変数 | ⭐⭐ 中級 | コンテナ環境 |
| 方法5: Docker Latest | Stdio | 最新 | 環境変数 | ⭐⭐ 中級 | コンテナ環境(最新版) |
| 開発版 | 両方 | ソース | 両方 | ⭐⭐⭐ 上級 | 開発・カスタマイズ |
通信モードの違い
Stdio Mode(標準入出力モード)
特徴:
- IBM Bobとの直接通信
- 環境変数で認証情報を管理
- シンプルで安全
- ローカル実行に最適
利点:
- ✅ 設定が簡単
- ✅ セキュリティが高い(認証情報が環境変数に保存)
- ✅ オーバーヘッドが少ない
欠点:
- ❌ リモートアクセス不可
- ❌ 複数クライアントからの同時アクセス不可
Streamable HTTP Mode(HTTPモード)
特徴:
- REST API経由での通信
- HTTPヘッダーで認証
- リクエストごとに異なる認証情報を使用可能
- ポート8080(デフォルト)でリッスン
利点:
- ✅ リモートアクセス可能
- ✅ 複数クライアントからの同時アクセス可能
- ✅ リクエストごとに異なる認証情報を使用可能
- ✅ 共有環境に適している
欠点:
- ❌ ネットワーク設定が必要
- ❌ セキュリティ設定に注意が必要
- ❌ 若干のオーバーヘッド
認証方式の違い
環境変数方式(Stdio Mode)
export INSTANA_BASE_URL="https://your-instana-instance.instana.io"
export INSTANA_API_TOKEN="your_instana_api_token"
利点:
- ✅ 設定が簡単
- ✅ 認証情報が設定ファイルに含まれない
- ✅ セキュリティが高い
欠点:
- ❌ 環境ごとに設定が必要
- ❌ 動的な認証情報変更が困難
HTTPヘッダー方式(HTTP Mode)
{
"args": [
"--header",
"instana-base-url: https://your-instana-instance.instana.io",
"--header",
"instana-api-token: your_instana_api_token"
]
}
利点:
- ✅ リクエストごとに異なる認証情報を使用可能
- ✅ 動的な認証情報変更が容易
- ✅ 複数のInstanaインスタンスに対応
欠点:
- ❌ 設定ファイルに認証情報が含まれる
- ❌ セキュリティ管理に注意が必要
ツールカテゴリの最適化
パフォーマンス向上のため、必要なツールカテゴリのみを有効化できます:
利用可能なカテゴリ
- infra: インフラストラクチャ監視ツール
- app: アプリケーション監視ツール(メトリクス、アラート、カタログ、トポロジー、分析、設定、グローバルアラート)
- events: イベント監視ツール(Kubernetesイベント、エージェント監視)
- website: ウェブサイト監視ツール(メトリクス、カタログ、分析、設定)
設定例
# 特定カテゴリのみ有効化
mcp-instana --tools infra,app
# すべてのカテゴリを有効化(デフォルト)
mcp-instana
トラブルシューティング
一般的な問題
1. SSL証明書エラー
問題: SSL証明書の検証エラーが発生する
解決策:
# Python環境に証明書をインストール
pip install certifi
2. ポート使用中エラー(HTTP Mode)
問題: ポート8080が既に使用されている
解決策:
# 別のポートを指定
mcp-instana --transport streamable-http --port 9000
3. 依存関係エラー
問題: 依存関係のインストールに失敗する
解決策:
# 依存関係を再同期
uv sync
# キャッシュをクリア
uv cache clean
4. 接続タイムアウト
問題: Instana APIへの接続がタイムアウトする
解決策:
- Instana Base URLが正しいか確認
- ネットワーク接続を確認
- ファイアウォール設定を確認
5. 認証エラー
問題: API Tokenが無効
解決策:
- Instana UIでAPI Tokenを再生成
- 環境変数またはヘッダーの設定を確認
IBM Bob GUI設定の詳細手順
GUI設定画面の使い方
IBM BobのGUI設定画面では、以下の項目を設定できます:
1. Installation Scope(インストールスコープ)
- Global: すべてのプロジェクトで使用可能
- Project: 特定のプロジェクトでのみ使用可能
推奨: 通常は Global を選択
2. Installation Method(インストール方式)
以下の5つから選択:
- UVX (Stdio Mode - Pinned Version) - 推奨
- UVX (Stdio Mode - Latest Version)
- NPX (Streamable HTTP Mode)
- Docker (Stdio Mode - Pinned Version)
- Docker (Stdio Mode - Latest Version)
3. Prerequisites(前提条件)
選択したインストール方法に応じて、必要な前提条件が表示されます:
- UVX方式: Python 3.10+、uv package manager
- NPX方式: Node.js、npm
- Docker方式: Docker
4. Configuration(設定)
必須項目:
-
Instana Base URL: InstanaインスタンスのURL
- 例:
https://ibmdevsandbox-instanaibm.instana.io
- 例:
-
Instana API Token: InstanaのAPIトークン
- 例:
2V9fgZ9dTBmr7p375O69BQ
- 例:
5. MCP Instana Version(バージョン)
インストールされているバージョンが表示されます(例: 0.7.1)
GUI設定の完全な手順
ステップ1: MCP設定画面を開く
- IBM Bobを起動
- 左側のサイドバーから MCP アイコンをクリック
- または、Settings → MCP を選択
ステップ2: Instana MCP Serverを検索
- Search MCP Servers 検索ボックスに「instana」と入力
- 検索結果から Instana を選択
- 「Installed / Global」または「Install」ボタンが表示されます
ステップ3: 設定画面を開く
- Instanaの項目をクリック
- Edit Parameters for Instana 画面が開きます
- 画面上部に「View Instana MCP documentation」リンクが表示されます
ステップ4: パラメータを設定
-
Installation Scope:
- Global を選択(推奨)- すべてのプロジェクトで使用
- または Project を選択 - 現在のプロジェクトのみ
-
Installation Method:
- ドロップダウンメニューをクリック
- 以下から選択:
-
UVX (Stdio Mode - Pinned Version)← 推奨 UVX (Stdio Mode - Latest Version)NPX (Streamable HTTP Mode)Docker (Stdio Mode - Pinned Version)Docker (Stdio Mode - Latest Version)
-
-
Prerequisites(前提条件の確認):
- 選択した方法に応じて必要な前提条件が表示されます
- 例: UVX方式の場合
- Python 3.10+
- uv package manager
-
Configuration(設定項目):
Instana Base URL:
- InstanaインスタンスのURLを入力
- 形式:
https://your-tenant-instanaibm.instana.io - 例:
https://ibmdevsandbox-instanaibm.instana.io
Instana API Token:
- InstanaのAPIトークンを入力
- Instana UIの Settings → Team Settings → API Tokens から取得
- 例:
2V9fgZ9dTBmr7p375O69BQ
-
MCP Instana Version(バージョン表示):
- インストール済みの場合、現在のバージョンが表示されます
- 例:
0.7.1
ステップ5: 設定を保存
- すべての項目を入力後、Update ボタンをクリック
- 設定が保存され、MCPサーバーがインストールされます
- インストール中は進行状況が表示されます
ステップ6: IBM Bobを再起動
- IBM Bobを完全に終了(Cmd+Q / Alt+F4)
- IBM Bobを再起動
ステップ7: 接続確認
- Settings → MCP を開く
- Instanaが「Installed / Global」として表示されていることを確認
- 緑色のインジケーター(●)が表示されていれば接続成功
- エラーがある場合は赤色のインジケーターとエラーメッセージが表示されます
GUI設定のトラブルシューティング
⚠️ 重要: Bobのモード設定
BobでMCPサーバーを使用する場合は、Advancedモードに設定する必要があります。他のモード(Plan、Code、Askなど)ではMCPサーバー機能は有効になりません。
モードの切り替え方法:
- IBM Bobの画面上部でモード選択ドロップダウンをクリック
- 🛠️ Advanced モードを選択
- MCPサーバーのツールが利用可能になります
インストールが失敗する場合
-
前提条件の確認:
- UVX方式:
uv --versionでuvがインストールされているか確認 - NPX方式:
node --versionとnpm --versionで確認 - Docker方式:
docker --versionで確認
- UVX方式:
-
ネットワーク接続の確認:
- インターネット接続を確認
- プロキシ設定が必要な場合は環境変数を設定
-
権限の確認:
- 管理者権限が必要な場合があります
- macOS/Linux:
sudoを使用する必要がある場合があります
接続エラーが表示される場合
-
Instana Base URLの確認:
- URLが正しいか確認(https://で始まる)
- 末尾にスラッシュ(/)がないことを確認
-
API Tokenの確認:
- トークンが有効か確認
- Instana UIで新しいトークンを生成して再試行
-
ファイアウォール設定:
- Instanaへのアクセスがブロックされていないか確認
サーバーステータスの確認
Stdio Mode
サーバーは起動後、標準入出力で通信を待機します。IBM Bobから接続されると自動的に通信が開始されます。
HTTP Mode
# ヘルスチェック
curl http://0.0.0.0:8080/mcp/
# カスタムポートの場合
curl http://0.0.0.0:9000/mcp/
セキュリティのベストプラクティス
- 環境変数の使用: 可能な限り環境変数で認証情報を管理
- 最小権限の原則: 必要最小限の権限を持つAPI Tokenを使用
- HTTPSの使用: Instana Base URLは必ずHTTPSを使用
- ファイアウォール設定: HTTP Modeの場合、必要なポートのみ開放
- 定期的な更新: セキュリティパッチを適用するため定期的に更新
まとめ
推奨インストール方法
- 個人利用・本番環境: 方法1(UVX Pinned Version)- GUI設定推奨
- 最新機能テスト: 方法2(UVX Latest Version)
- 共有環境・複数認証: 方法3(NPX HTTP Mode)
- コンテナ環境: 方法4または5(Docker)
- 開発・カスタマイズ: 開発版(ソースから実行)
次のステップ
- 適切なインストール方法を選択
- 前提条件を満たす
- IBM BobのGUI設定またはファイル編集でインストール
- IBM Bobで接続確認
- Instanaツールを活用
IBM Bob設定ファイルの場所
macOS
~/.bob/settings/mcp_settings.json
Windows
%USERPROFILE%\.bob\settings\mcp_settings.json
Linux
~/.bob/settings/mcp_settings.json
設定ファイルの例
{
"mcpServers": {
"instana": {
"command": "uvx",
"args": [
"mcp-instana",
"--transport",
"stdio"
],
"env": {
"INSTANA_BASE_URL": "https://ibmdevsandbox-instanaibm.instana.io",
"INSTANA_API_TOKEN": "2V9fgZ9dTBmr7p375O69BQ"
}
}
}
}
注意:
- 設定ファイルを直接編集した場合は、IBM Bobを再起動してください
- GUI設定を使用する場合は、設定ファイルを手動で編集する必要はありません
最後で
今IBM Bobを無料で始めることはできます。
30日間の無料トライアルでは、IBM Bobの利用に必要なクレジット”Bobコイン”を、40Bobコイン分ご利用いただけます。お申し込みはこちらから行えます。
たくさん活用いただける場合に、Bobコインの追加が必要な場合は、こちらから少額よりご購入いただけます。