IBM watsonx.ai Granite

@three-ws/ibm-watsonx-mcp

适用于 IBM watsonx.ai 的 MCP 服务 — 在你自己的 IBM Cloud 账户中使用聊天、生成、嵌入、分词、预测和模型发现功能。

安装 · 快速开始 · 工具 · 要求 · three.ws

---

一个 Model Context Protocol 服务，可将 IBM watsonx.ai — IBM Granite 基础模型以及你账户中的其他所有模型 — 提供给 Claude Desktop、Claude Code 和 Cursor 等 MCP 客户端。它使用你自己的 IBM Cloud 凭据，直接调用 watsonx.ai 即服务 REST API：根据你的 API 密钥获取 IAM bearer 令牌，在令牌即将过期前将其缓存，并将每次调用限定在你的项目范围内。没有中间后端，没有遥测数据，也没有模拟数据。

由社区构建，与 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 中，只需运行一条命令：

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

重启客户端后，下方的六个工具便会显示。使用 MCP Inspector 手动检查可用功能：

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

工具

工具	功能
watsonx_chat	根据角色/内容消息列表生成聊天回复。返回回复内容及令牌用量。
watsonx_generate	使用解码控制（贪心/采样、停止序列）生成原始提示词补全。
watsonx_embed	为一段或多段文本生成嵌入向量（最多 1000 段）。每段输入对应一个向量，并返回维度信息。
watsonx_tokenize	根据模型分词器统计文本的令牌数量（也可选择返回令牌）。
watsonx_forecast	使用 IBM Granite TimeSeries（TinyTimeMixer）模型进行零样本时间序列预测。
watsonx_list_models	列出你的账户和区域可用的基础模型，也可按条件筛选。

每个工具都是只读的模型推理调用，不会修改你的环境或 IBM 账户，并且声明了 MCP 工具注解（readOnlyHint、openWorldHint、idempotentHint），以便客户端判断其副作用。

输入参数

watsonx_chat — messages（必填：由 { role, content } 组成的数组，角色为 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 会被交换为短期 IAM bearer token，交换地址为 https://iam.cloud.ibm.com/identity/token（grant_type=urn:ibm:params:oauth:grant-type:apikey）。该令牌会缓存在进程内，并在过期前约五分钟刷新。除这一次 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 Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}