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

Tool	Description
`watsonx_generate`	Generate text using watsonx.ai models
`watsonx_chat`	Chat with watsonx.ai models
`watsonx_embeddings`	Generate text embeddings
`watsonx_list_models`	List available models

Setup

1. Install Dependencies

bash

cd ~/watsonx-mcp-server
npm install

2. Configure Environment

Set these environment variables:

bash

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:

config.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:

Code

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

Code

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:

Claude (Opus 4.5) - Primary reasoning agent, handles complex tasks
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:

Code

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

bash

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

bash

./demo-external-drive.sh

Embedding Index & RAG

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

bash

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

bash

# 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