npm package: @purplesquirrel/ibmz-mcp-server
Description: MCP server for IBM Z mainframe integration - Key Protect HSM and z/OS Connect
Author: Matthew Karsten
Latest version: 1.0.3

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![npm version](https://img.shields.io/npm/v/@purplesquirrel/ibmz-mcp-server.svg)](https://www.npmjs.com/package/@purplesquirrel/ibmz-mcp-server) [![npm downloads](https://img.shields.io/npm/dm/@purplesquirrel/ibmz-mcp-server.svg)](https://www.npmjs.com/package/@purplesquirrel/ibmz-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)
[![IBM Z](https://img.shields.io/badge/IBM-Z_Mainframe-052FAD)](https://www.ibm.com/z)
[![CI](https://github.com/PurpleSquirrelMedia/ibmz-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/PurpleSquirrelMedia/ibmz-mcp-server/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PurpleSquirrelMedia/ibmz-mcp-server/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PurpleSquirrelMedia/ibmz-mcp-server)

# IBM Z MCP Server

MCP server for IBM Z mainframe integration with Claude Code. Provides access to enterprise-grade security and mainframe capabilities.

## Features

- **Key Protect** - HSM-backed key management (FIPS 140-2 Level 3)
- **z/OS Connect** - REST APIs to mainframe programs (CICS, IMS, batch)

## Available Tools

### Key Protect (HSM Key Management)

| Tool | Description |
|------|-------------|
| `key_protect_list_keys` | List encryption keys in Key Protect |
| `key_protect_create_key` | Create root or standard keys |
| `key_protect_get_key` | Get key details and metadata |
| `key_protect_wrap_key` | Wrap (encrypt) DEKs with a root key |
| `key_protect_unwrap_key` | Unwrap (decrypt) wrapped DEKs |
| `key_protect_rotate_key` | Rotate a root key |
| `key_protect_delete_key` | Delete a key (irreversible) |
| `key_protect_get_key_policies` | Get key policies |

### z/OS Connect (Mainframe Integration)

| Tool | Description |
|------|-------------|
| `zos_connect_list_services` | List available mainframe services |
| `zos_connect_get_service` | Get service details and OpenAPI spec |
| `zos_connect_call_service` | Call a mainframe service via REST |
| `zos_connect_list_apis` | List API requester configurations |
| `zos_connect_health` | Check z/OS Connect server health |

## Setup

### 1. Install Dependencies

```bash
cd ~/ibmz-mcp-server
npm install
```

### 2. Configure Environment

**For Key Protect:**
```bash
IBM_CLOUD_API_KEY=your-ibm-cloud-api-key
KEY_PROTECT_INSTANCE_ID=your-key-protect-instance-id
KEY_PROTECT_URL=https://us-south.kms.cloud.ibm.com
```

**For z/OS Connect (requires mainframe access):**
```bash
ZOS_CONNECT_URL=https://your-mainframe:9443/zosConnect
ZOS_CONNECT_USERNAME=your-username
ZOS_CONNECT_PASSWORD=your-password
```

### 3. Add to Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "ibmz": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/matthewkarsten/ibmz-mcp-server/index.js"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-api-key",
        "KEY_PROTECT_INSTANCE_ID": "your-instance-id"
      }
    }
  }
}
```

## Architecture

```
Claude Code (Opus 4.5)
         │
         └──▶ IBM Z MCP Server
                    │
                    ├──▶ Key Protect (HSM)
                    │         │
                    │         └── FIPS 140-2 Level 3 HSM
                    │
                    └──▶ z/OS Connect
                              │
                              ├── CICS Transactions
                              ├── IMS Programs
                              └── Batch Jobs
```

## Key Concepts

### Envelope Encryption with Key Protect

Key Protect enables envelope encryption:

1. **Root Keys (KEK)** - Stored in HSM, never leave the hardware
2. **Data Encryption Keys (DEK)** - Wrapped by root keys
3. **Wrap/Unwrap** - Operations to protect DEKs

```
Data → Encrypt with DEK → Ciphertext
DEK  → Wrap with KEK   → Wrapped DEK (stored alongside ciphertext)
```

### z/OS Connect Integration

z/OS Connect provides REST APIs to mainframe programs:

- **CICS** - Online transaction processing
- **IMS** - Hierarchical database and transactions
- **Batch** - Scheduled batch processing
- **Db2** - Relational database access

JSON payloads are automatically mapped to COBOL copybooks.

## Use Cases

### Enterprise Key Management
- Manage encryption keys for cloud workloads
- Bring Your Own Key (BYOK) to IBM Cloud services
- Key rotation for compliance
- Envelope encryption for data at rest

### Mainframe Modernization
- Expose COBOL programs as REST APIs
- Integrate mainframe data with cloud applications
- AI-powered mainframe operations via Claude
- Modernize without rewriting legacy code

## IBM Cloud Resources

This MCP server can use:
- **Service**: Key Protect
- **Plan**: Tiered (first 20 keys free)
- **Region**: us-south

For z/OS Connect, you need:
- IBM mainframe with z/OS
- z/OS Connect EE installed
- Network access from your machine

## Demo Scripts

Run these demos to test the integration:

```bash
# Set environment
export IBM_CLOUD_API_KEY="your-key"
export KEY_PROTECT_INSTANCE_ID="your-instance-id"

# Full 5-service pipeline (NLU → watsonx → Key Protect → Cloudant → TTS)
node demo-full-stack.js

# End-to-end workflow (NLU → Key Protect → Cloudant)
node demo-e2e-workflow.js

# Test envelope encryption (HSM wrap/unwrap)
node test-envelope-encryption.js

# Watson services suite test
node demo-watson-suite.js
```

### Integration Status (Verified Dec 15, 2025)

| Service | Feature | Status |
|---------|---------|--------|
| Key Protect | List Keys | ✅ Working |
| Key Protect | Create Key | ✅ Working |
| Key Protect | Wrap DEK | ✅ Working |
| Key Protect | Unwrap DEK | ✅ Working |
| Key Protect | Rotate Key | ✅ Working |
| watsonx.ai | List Models | ✅ Working |
| Watson NLU | Sentiment/Entities | ✅ Working |
| Watson TTS | Voice Synthesis | ✅ Working |
| Cloudant | Document Storage | ✅ Working |

## Files

```
ibmz-mcp-server/
├── index.js                    # MCP server implementation
├── package.json                # Dependencies
├── docs/                       # GitHub Pages documentation
│   ├── index.html             # Main documentation
│   └── specs.html             # Technical specifications
├── demo-full-stack.js          # Full 5-service pipeline
├── demo-e2e-workflow.js        # NLU → Key Protect → Cloudant
├── demo-watson-suite.js        # All Watson services test
├── test-envelope-encryption.js # HSM wrap/unwrap test
└── README.md                   # This file
```

## Related MCP Servers

- [watsonx-mcp-server](https://github.com/PurpleSquirrelMedia/watsonx-mcp-server) - Foundation models (Granite, Llama, Mistral)

## 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:enterprise@purplesquirrel.media) for SLAs, custom development, and priority support.