IBM watsonx.ai Granite

@three-ws/ibm-watsonx-mcp

IBM watsonx.ai 用 MCP サーバーです。チャット、生成、埋め込み、トークン化、予測、モデル検索を、お客様自身の IBM Cloud アカウント上で実行できます。

インストール · クイックスタート · ツール · 要件 · three.ws

---

IBM watsonx.ai（IBM Granite 基盤モデルや、お客様のアカウント内で利用できるその他のモデル）を、Claude Desktop、Claude Code、Cursor などの MCP クライアントに公開する、Model Context Protocol サーバーです。お客様自身の IBM Cloud 認証情報を使用し、watsonx.ai の as-a-Service REST API に直接接続します。API キーから IAM ベアラートークンを発行し、有効期限の直前までキャッシュして、すべての呼び出しをお客様のプロジェクトに限定します。中間バックエンド、テレメトリー、モックデータはありません。

コミュニティによって開発されており、IBM とは提携していません。レジストリ名：io.github.nirholas/ibm-watsonx。

インストール

npm install @three-ws/ibm-watsonx-mcp

npx で直接実行できます（インストール不要です）。

WATSONX_API_KEY=... WATSONX_PROJECT_ID=... npx @three-ws/ibm-watsonx-mcp

または、グローバルにインストールすると、PATH 上で ibm-watsonx-mcp バイナリを利用できます。

npm install -g @three-ws/ibm-watsonx-mcp

クイックスタート

Claude Code なら、次の 1 つのコマンドで実行できます。

claude mcp add ibm-watsonx -e WATSONX_API_KEY=... -e WATSONX_PROJECT_ID=... -- npx -y @three-ws/ibm-watsonx-mcp

または、MCP クライアントの設定ファイル（claude_desktop_config.json、Cursor の mcp.json）にサーバーを追加します。

{
	"mcpServers": {
		"ibm-watsonx": {
			"command": "npx",
			"args": ["-y", "@three-ws/ibm-watsonx-mcp"],
			"env": {
				"WATSONX_API_KEY": "your-ibm-cloud-api-key",
				"WATSONX_PROJECT_ID": "your-watsonx-project-id"
			}
		}
	}
}

クライアントを再起動すると、以下の 6 つのツールが表示されます。MCP Inspector を使って、ツールの一覧を手動で確認できます。

npx -y @modelcontextprotocol/inspector npx @three-ws/ibm-watsonx-mcp

ツール

ツール	機能
watsonx_chat	ロールと内容のメッセージリストからチャット補完を実行します。応答とトークン使用量を返します。
watsonx_generate	デコード制御（greedy/sample、停止シーケンス）を指定して、プロンプトを補完します。
watsonx_embed	1 件以上のテキスト（最大 1000 件）の埋め込みベクトルを生成します。入力ごとに 1 つのベクトルと次元数を返します。
watsonx_tokenize	モデルのトークナイザーを使って、テキストのトークン数（およびオプションでトークン）を返します。
watsonx_forecast	IBM Granite TimeSeries（TinyTimeMixer）モデルによるゼロショット時系列予測を実行します。
watsonx_list_models	お客様のアカウントおよびリージョンで利用可能な基盤モデルを一覧表示します。必要に応じて絞り込めます。

すべてのツールは読み取り専用のモデル推論呼び出しであり、お客様の環境や IBM アカウントを変更しません。また、MCP ツールのアノテーション（readOnlyHint、openWorldHint、idempotentHint）を宣言しているため、クライアントは副作用を判断できます。

入力パラメーター

watsonx_chat — messages（必須：{ role, content } の配列、role は system／user／assistant）、model、max_tokens（1～4096）、temperature（0～2）、top_p（0～1）。

watsonx_generate — input（必須）、model、max_new_tokens（1～4096）、temperature（0～2）、decoding_method（greedy／sample）、stop_sequences。

watsonx_embed — inputs（必須：1～1000 件のテキスト）、model。

watsonx_tokenize — input（必須）、model、return_tokens（ブール値）。

watsonx_forecast — timestamps（必須：ISO-8601、一定間隔、古い順）、values（必須：数値、同じ長さ）、freq（必須：pandas の頻度指定、例：1h、15min、1D）、model、target_column、prediction_length（1～96）。

watsonx_list_models — filter（例：function_text_generation、function_embedding）、limit（1～200、デフォルトは100）。

呼び出し例

// watsonx_chat
{ "messages": [{ "role": "user", "content": "Explain MCP in one sentence." }] }

// watsonx_generate
{ "input": "Write a haiku about Kubernetes.", "decoding_method": "sample", "temperature": 0.7, "max_new_tokens": 60 }

// watsonx_embed
{ "inputs": ["lakehouse", "data warehouse"] }

// watsonx_forecast
{ "timestamps": ["2025-01-01T00:00:00Z", "2025-01-01T01:00:00Z"], "values": [1200, 1180], "freq": "1h", "prediction_length": 24 }

// watsonx_list_models
{ "filter": "function_embedding" }

認証の仕組み

WATSONX_API_KEY は、https://iam.cloud.ibm.com/identity/token（grant_type=urn:ibm:params:oauth:grant-type:apikey）で有効期間の短い IAM ベアラートークンと交換されます。トークンはプロセス内にキャッシュされ、有効期限の約5分前に更新されます。この1回の IAM 交換を除き、API キーがマシンの外に送信されることはありません。

要件

• Node.js >= 20。
• watsonx.ai がプロビジョニングされた IBM Cloud アカウント — サインアップ（無料枠を利用できます）。
• IBM Cloud API キー — https://cloud.ibm.com/iam/apikeys で作成してください。
• watsonx.ai プロジェクト ID — プロジェクトを開き → Manage → General → Project ID（またはデプロイメント・スペース ID）を確認してください。

環境変数

変数	必須	デフォルト
WATSONX_API_KEY	はい	—
WATSONX_PROJECT_ID	はい（または WATSONX_SPACE_ID）	—
WATSONX_SPACE_ID	WATSONX_PROJECT_ID の代替	—
WATSONX_URL	いいえ	https://us-south.ml.cloud.ibm.com
WATSONX_MODEL_ID	いいえ	ibm/granite-3-8b-instruct
WATSONX_EMBED_MODEL_ID	いいえ	ibm/granite-embedding-278m-multilingual
WATSONX_FORECAST_MODEL	いいえ	ibm/granite-ttm-512-96-r2
WATSONX_API_VERSION	いいえ	2024-05-31
WATSONX_TS_API_VERSION	いいえ	2025-02-11（時系列 API の日付）
WATSONX_TIMEOUT_MS	いいえ	60000
WATSONX_IAM_URL	いいえ	https://iam.cloud.ibm.com/identity/token

リージョン別ホスト：us-south、eu-de、eu-gb、jp-tok、au-syd、ca-tor — 例：https://eu-de.ml.cloud.ibm.com。

関連

• @three-ws/ibm-x402-mcp — 同じ IBM Granite ツールを従量課金制の x402 エンドポイント（Solana 上の USDC）として提供します。これにより、呼び出し元が IBM アカウントを用意する必要はありません。

リンク

• ホームページ：https://three.ws
• 変更履歴：https://three.ws/changelog
• 問題：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0、LICENSE を参照

---

_{three.ws SDK スイートの一部 — 3D AI エージェント、オンチェーン ID、エージェント決済。
ウェブサイト · 変更履歴 · GitHub}