Watsonx

watsonx MCP Server

MCP server for IBM watsonx.ai integration with Claude Code. Enables Claude to delegate tasks to IBM's foundation models (Granite, Llama, Mistral, etc.).

Features

• Text Generation - Generate text using watsonx.ai foundation models
• Chat - Have conversations with watsonx.ai chat models
• Embeddings - Generate text embeddings
• Model Listing - List all available foundation models

Available Tools

Setup

1. Install Dependencies

cd ~/watsonx-mcp-server

npm install

2. Configure Environment

Set these environment variables:

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

Note: Either WATSONX_SPACE_ID or WATSONX_PROJECT_ID is required for text generation, embeddings, and chat. Deployment spaces are recommended as they have Watson Machine Learning (WML) pre-configured.

3. Add to Claude Code

The MCP server is already configured in ~/.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" } } } }

Usage

Once configured, Claude can use watsonx.ai tools:

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

Available Models

Some notable models available:

• ibm/granite-3-3-8b-instruct - IBM Granite 3.3 8B (recommended)
• ibm/granite-13b-chat-v2 - IBM Granite chat model
• ibm/granite-3-8b-instruct - Granite 3 instruct model
• meta-llama/llama-3-70b-instruct - Meta's Llama 3 70B
• mistralai/mistral-large - Mistral AI large model
• ibm/slate-125m-english-rtrvr-v2 - Embedding model

Use watsonx_list_models to see all available models.

Architecture

Claude Code (Opus 4.5)

│ └──▶ watsonx MCP Server │ └──▶ IBM watsonx.ai API │ ├── Granite Models ├── Llama Models ├── Mistral Models └── Embedding Models

Two-Agent System

This enables a two-agent architecture where:

1. Claude (Opus 4.5) - Primary reasoning agent, handles complex tasks
2. watsonx.ai - Secondary agent for specific workloads

Claude can delegate tasks to watsonx.ai when:

• IBM-specific model capabilities are needed
• Running batch inference on enterprise data
• Using specialized Granite models
• Generating embeddings for RAG pipelines

IBM Cloud Resources

This MCP server uses:

• Service: watsonx.ai Studio (data-science-experience)
• Plan: Lite (free tier)
• Region: us-south

Create your own watsonx.ai project and deployment space in IBM Cloud.

Integration with IBM Z MCP Server

This watsonx MCP server works alongside the IBM Z MCP server:

Claude Code (Opus 4.5)

│ ├──▶ watsonx MCP Server │ └── Text generation, embeddings, chat │ └──▶ ibmz MCP Server └── Key Protect HSM, z/OS Connect

Demo scripts in the ibmz-mcp-server:

• demo-full-stack.js - Full 5-service pipeline
• demo-rag.js - RAG with watsonx embeddings + Granite

Document Analyzer

The document analyzer (document-analyzer.js) provides powerful tools for analyzing your external drive data using watsonx.ai:

Commands

# 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'

Features

• Summarization: Generate concise summaries of any document
• Analysis: Extract document type, topics, entities, and sentiment
• Q&A: Ask natural language questions about document content
• Embeddings: Generate 768-dimensional vectors for semantic search
• Semantic Search: Find similar documents using vector similarity

Demo

Run the full demo:

./demo-external-drive.sh

Embedding Index & RAG

The embedding-index.js tool provides semantic search and RAG (Retrieval Augmented Generation):

# 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

The batch-processor.js tool processes multiple documents at once:

# 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

Categories: technical, business, creative, personal, code, legal, marketing, educational, other

Files

• index.js - MCP server implementation
• document-analyzer.js - Document analysis CLI tool
• embedding-index.js - Embedding index and RAG tool
• batch-processor.js - Batch document processor
• demo-external-drive.sh - Demo script
• package.json - Dependencies
• README.md - This file

Author

Matthew Karsten

License

MIT