io.github.ExpertVagabond/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