# watsonx MCP Server

[![npm version](https://img.shields.io/npm/v/@purplesquirrel/watsonx-mcp-server)](https://npmjs.com/package/@purplesquirrel/watsonx-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@purplesquirrel/watsonx-mcp-server)](https://npmjs.com/package/@purplesquirrel/watsonx-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![watsonx](https://img.shields.io/badge/IBM-watsonx-052FAD)](https://www.ibm.com/watsonx)
[![CI](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PurpleSquirrelMedia/watsonx-mcp-server/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PurpleSquirrelMedia/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`:

```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

```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


## 💜 Support This Project

If this MCP server is useful to you, consider supporting its development:

[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?style=for-the-badge&logo=github)](https://github.com/sponsors/PurpleSquirrelMedia)
[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/purplesquirrel)

**Enterprise support available** - [Contact us](mailto:[email protected]) for SLAs, custom development, and priority support.