@three-ws/ibm-watsonx-mcp

MCP server for IBM watsonx.ai — chat, generation, embeddings, tokenization, forecasting, and model discovery, on your own IBM Cloud account.

Install · Quick start · Tools · Requirements · three.ws

A Model Context Protocol server that exposes IBM watsonx.ai — IBM Granite foundation models and anything else in your account — to MCP clients such as Claude Desktop, Claude Code, and Cursor. It talks directly to the watsonx.ai as-a-Service REST API with your own IBM Cloud credentials: it mints an IAM bearer token from your API key, caches it until just before expiry, and scopes every call to your project. No intermediary backend, no telemetry, no mock data.

Community-built and not affiliated with IBM. Registry name: io.github.nirholas/ibm-watsonx.

Install

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

Run it directly with npx (no install needed):

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

Or install globally to get the ibm-watsonx-mcp binary on your PATH:

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

Quick start

With Claude Code, one command:

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

Or add the server to your MCP client config (claude_desktop_config.json, Cursor's 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"
			}
		}
	}
}

Restart the client and the six tools below appear. Inspect the surface manually with the MCP Inspector:

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

Tools

Every tool is a read-only model-inference call — nothing in your environment or IBM account is modified — and declares MCP tool annotations (readOnlyHint, openWorldHint, idempotentHint) so clients can reason about side effects.

Input parameters

watsonx_chat — messages (required: array of { role, content }, roles system/user/assistant), model, max_tokens (1–4096), temperature (0–2), top_p (0–1).

watsonx_generate — input (required), model, max_new_tokens (1–4096), temperature (0–2), decoding_method (greedy/sample), stop_sequences.

watsonx_embed — inputs (required: 1–1000 texts), model.

watsonx_tokenize — input (required), model, return_tokens (boolean).

watsonx_forecast — timestamps (required: ISO-8601, uniform cadence, oldest first), values (required: numeric, same length), freq (required: pandas cadence, e.g. 1h, 15min, 1D), model, target_column, prediction_length (1–96).

watsonx_list_models — filter (e.g. function_text_generation, function_embedding), limit (1–200, default 100).

Example calls

// 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" }

How auth works

WATSONX_API_KEY is exchanged for a short-lived IAM bearer token at https://iam.cloud.ibm.com/identity/token (grant_type=urn:ibm:params:oauth:grant-type:apikey). The token is cached in-process and refreshed about five minutes before it expires. Your API key never leaves your machine except in that single IAM exchange.

Requirements

• Node.js >= 20.
• An IBM Cloud account with watsonx.ai provisioned — sign up (free tier available).
• An IBM Cloud API key — create one at https://cloud.ibm.com/iam/apikeys.
• Your watsonx.ai project id — open the project → Manage → General → Project ID (or a deployment space id).

Environment variables

Regional hosts: us-south, eu-de, eu-gb, jp-tok, au-syd, ca-tor — e.g. https://eu-de.ml.cloud.ibm.com.

Related

• @three-ws/ibm-x402-mcp — the same IBM Granite tools as pay-per-use x402 endpoints (USDC on Solana), so callers need no IBM account of their own.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

_{Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub}