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

cd ~/ibmz-mcp-server
npm install

2. Configure Environment

For Key Protect:

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

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:

{
  "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:

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

Enterprise support available - Contact us for SLAs, custom development, and priority support.