内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/ibm-watsonx-mcp</h1>
<p align="center"><strong>MCP 服务器，用于 IBM watsonx.ai — 聊天、生成、嵌入、标记化、预测和模型发现，均在您自己的 IBM Cloud 账户上。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/ibm-watsonx-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/ibm-watsonx-mcp?logo=npm&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@three-ws/ibm-watsonx-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/ibm-watsonx-mcp?color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/ibm-watsonx-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/ibm-watsonx-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas%2Fibm--watsonx-6e56cf"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
<p align="center">
<a href="#安装">安装</a> ·
<a href="#快速开始">快速开始</a> ·
<a href="#工具">工具</a> ·
<a href="#需求">需求</a> ·
<a href="https://three.ws">three.ws</a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，暴露 IBM watsonx.ai — IBM Granite 基础模型和您账户中的其他内容 — 给 MCP 客户端，如 Claude Desktop、Claude Code 和 Cursor。它直接与 watsonx.ai 即服务 REST API 通信，使用您自己的 IBM Cloud 凭证：它从您的 API 密钥中生成一个 IAM 持有者令牌，缓存它直到过期前， 并将每个调用限定在您的项目范围内。没有中间后端，没有遥测数据，没有模拟数据。
> 社区构建，不隶属于 IBM。注册名称：`io.github.nirholas/ibm-watsonx`.
## 安装
```bash
npm install @three-ws/ibm-watsonx-mcp
```
直接使用 `npx` 运行（无需安装）：
```bash
WATSONX_API_KEY=... WATSONX_PROJECT_ID=... npx @three-ws/ibm-watsonx-mcp
```
或全局安装以获取 `ibm-watsonx-mcp` 二进制文件在您的 `PATH` 上：
```bash
npm install -g @three-ws/ibm-watsonx-mcp
```
## 快速开始
与 Claude Code 结合使用，一个命令：
```bash
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`）：
```json
{
"mcpServers": {
"ibm-watsonx": {
"command": "npx",
"args": ["-y", "@three-ws/ibm-watsonx-mcp"],
"env": {
"WATSONX_API_KEY": "您的 IBM Cloud API 密钥",
"WATSONX_PROJECT_ID": "您的 watsonx 项目 ID"
}
}
}
}
```
重启客户端，六种工具如下所示。使用 MCP 检查器手动检查界面：
```bash
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）。
### 示例调用
```jsonc
// watsonx_chat
{ "messages": [{ "role": "user", "content": "用一句话解释 MCP。" }] }
// watsonx_generate
{ "input": "写一首关于 Kubernetes 的俳句。", "decoding_method": "sample", "temperature": 0.7, "max_new_tokens": 60 }
// watsonx_embed
{ "inputs": ["lakehouse", "数据仓库"] }
// 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` 处的一个短期 IAM 持有者令牌（`grant_type=urn:ibm:params:oauth:grant-type:apikey`）。令牌在进程中缓存，并在过期前约 5 分钟刷新。您的 API 密钥除了在单个 IAM 交换中之外，永远不会离开您的机器。
## 需求
- **Node.js >= 20.**
- 一个具有 watsonx.ai 配置的 IBM Cloud 账户 — [注册](https://dataplatform.cloud.ibm.com/registration/stepone?context=wx)（免费层可用）。
- 一个 **IBM Cloud API 密钥** — 在 <https://cloud.ibm.com/iam/apikeys> 处创建。
- 您的 **watsonx.ai 项目 ID** — 打开项目 → **管理** → **常规** → **项目 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_API_VERSION` | 否 | `2024-05-31` |
区域主机：`us-south`、`eu-de`、`eu-gb`、`jp-tok`、`au-syd`、`ca-tor` — 例如 `https://eu-de.ml.cloud.ibm.com`.
## 相关
- [`@three-ws/ibm-x402-mcp`](https://www.npmjs.com/package/@three-ws/ibm-x402-mcp) — 与按使用量计费的 x402 端点（Solana 上的 USDC）相同的 IBM Granite 工具，因此调用者无需自己的 IBM 账户。
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
本软件是专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
