watsonx

watsonx MCP 服务

用于将 IBM watsonx.ai 集成到 Claude Code 的 MCP 服务。使 Claude 能够将任务委托给 IBM 的基础模型（Granite、Llama、Mistral 等）。

功能

• 文本生成 - 使用 watsonx.ai 基础模型生成文本
• 聊天 - 与 watsonx.ai 聊天模型进行对话
• 嵌入 - 生成文本嵌入
• 模型列表 - 列出所有可用的基础模型

可用工具

工具	描述
watsonx_generate	使用 watsonx.ai 模型生成文本
watsonx_chat	与 watsonx.ai 模型聊天
watsonx_embeddings	生成文本嵌入
watsonx_list_models	列出可用模型

设置

1. 安装依赖项

cd ~/watsonx-mcp-server
npm install

2. 配置环境

设置以下环境变量：

WATSONX_API_KEY=your-ibm-cloud-api-key
WATSONX_URL=https://us-south.ml.cloud.ibm.com
WATSONX_SPACE_ID=your-deployment-space-id  # Recommended: deployment space
WATSONX_PROJECT_ID=your-project-id          # Alternative: project ID

注意：文本生成、嵌入和聊天需要设置 WATSONX_SPACE_ID 或 WATSONX_PROJECT_ID。建议使用部署空间，因为其中已预配置 Watson Machine Learning（WML）。

3. 添加到 Claude Code

MCP 服务已在 ~/.claude.json 中配置：

{
  "mcpServers": {
    "watsonx": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/matthewkarsten/watsonx-mcp-server/index.js"],
      "env": {
        "WATSONX_API_KEY": "your-api-key",
        "WATSONX_URL": "https://us-south.ml.cloud.ibm.com",
        "WATSONX_SPACE_ID": "your-deployment-space-id"
      }
    }
  }
}

使用方法

配置完成后，Claude 即可使用 watsonx.ai 工具：

User: Use watsonx to generate a haiku about coding

Claude: [Uses watsonx_generate tool]
Result: Code flows like water
       Bugs arise, then disappear
       Programs come alive

可用模型

部分值得关注的可用模型：

• ibm/granite-3-3-8b-instruct - IBM Granite 3.3 8B（推荐）
• ibm/granite-13b-chat-v2 - IBM Granite 聊天模型
• ibm/granite-3-8b-instruct - Granite 3 指令模型
• meta-llama/llama-3-70b-instruct - Meta 的 Llama 3 70B
• mistralai/mistral-large - Mistral AI 大型模型
• ibm/slate-125m-english-rtrvr-v2 - 嵌入模型

使用 watsonx_list_models 查看所有可用模型。

架构

Claude Code (Opus 4.5)
         │
         └──▶ watsonx MCP Server
                    │
                    └──▶ IBM watsonx.ai API
                              │
                              ├── Granite Models
                              ├── Llama Models
                              ├── Mistral Models
                              └── Embedding Models

双 Agent 系统

这实现了双 Agent 架构，其中：

1. Claude（Opus 4.5） - 主推理 Agent，处理复杂任务
2. watsonx.ai - 用于特定工作负载的辅助 Agent

在以下情况下，Claude 可以将任务委托给 watsonx.ai：

• 需要 IBM 特有的模型能力
• 对企业数据运行批量推理
• 使用专用 Granite 模型
• 为 RAG 流水线生成嵌入

IBM Cloud 资源

此 MCP 服务使用：

• 服务：watsonx.ai Studio（data-science-experience）
• 方案：Lite（免费层级）
• 区域：us-south

在 IBM Cloud 中创建自己的 watsonx.ai 项目和部署空间。

与 IBM Z MCP 服务集成

此 watsonx MCP 服务可与 IBM Z MCP 服务协同工作：

Claude Code (Opus 4.5)
         │
         ├──▶ watsonx MCP Server
         │         └── Text generation, embeddings, chat
         │
         └──▶ ibmz MCP Server
                   └── Key Protect HSM, z/OS Connect

ibmz-mcp-server 中的演示脚本：

• demo-full-stack.js - 完整的 5 服务流水线
• demo-rag.js - 使用 watsonx 嵌入和 Granite 的 RAG

文档分析器

文档分析器（document-analyzer.js）提供强大的工具，可使用 watsonx.ai 分析外部驱动器中的数据：

命令

# View document catalog (9,168 documents)
node document-analyzer.js catalog

# Summarize a document
node document-analyzer.js summarize 1002519.txt

# Analyze document type, topics, entities
node document-analyzer.js analyze 1002519.txt

# Ask questions about a document
node document-analyzer.js question 1002519.txt 'What AWS credentials are needed?'

# Generate embeddings for documents
node document-analyzer.js embed

# Semantic search across documents
node document-analyzer.js search 'IBM Cloud infrastructure'

功能

• 摘要：为任意文档生成简洁摘要
• 分析：提取文档类型、主题、实体和情感倾向
• 问答：使用自然语言提问，了解文档内容
• 嵌入：生成 768 维向量，用于语义搜索
• 语义搜索：使用向量相似度查找相似文档

演示

运行完整演示：

./demo-external-drive.sh

嵌入索引与 RAG

embedding-index.js 工具提供语义搜索和 RAG（检索增强生成）：

# Build an embedding index (50 documents)
node embedding-index.js build 50

# Semantic search
node embedding-index.js search 'cloud infrastructure'

# RAG query - retrieves relevant docs and generates answer
node embedding-index.js rag 'How do I set up AWS for Satellite?'

# Show index statistics
node embedding-index.js stats

批处理器

batch-processor.js 工具可一次处理多个文档：

# Classify documents into categories
node batch-processor.js classify 20

# Extract topics from documents
node batch-processor.js topics 15

# Generate one-line summaries
node batch-processor.js summarize 10

# Full analysis (classify + topics + summary)
node batch-processor.js full 10

类别：技术、商业、创意、个人、代码、法律、营销、教育、其他

文件

• index.js - MCP 服务实现
• document-analyzer.js - 文档分析命令行工具
• embedding-index.js - 嵌入索引和 RAG 工具
• batch-processor.js - 文档批处理器
• demo-external-drive.sh - 演示脚本
• package.json - 依赖项
• README.md - 本文件

作者

Matthew Karsten

许可证

MIT