AI agents meet IBM z/OS

What it does

mainframe-mcp-server turns z/OS capabilities into MCP tools an AI agent can call. Instead of typing Zowe CLI commands, you ask in natural language — “why did PAYJOB01 fail?” — and the agent invokes the right tool with validated inputs and structured output.

How it's different

This server fills a gap cloud-native MCP tools cannot: governed, structured access to the mainframe for AI workflows.

Swipe horizontally to see all columns →

Features

Organized into core tooling, operational intelligence, optional enterprise integrations, and security controls.

Tools reference

Full input/output details: tools-reference.md. Every tool accepts an optional environment argument when multi-environment is configured (see Enterprise).

Setup instructions

Requirements: Node.js 18+, reachable z/OSMF endpoint, valid z/OS credentials (user/password or token).

Option A — Install via npm (recommended)

Published as @notharshhaa/mainframe-mcp-server. Listed on the MCP registry.

1. Add to your MCP client

   Cursor: ~/.cursor/mcp.json · VS Code: MCP settings · Claude Desktop: claude_desktop_config.json

2. Paste the server block

   The IDE installer may prompt for values from server.json. Credentials go in the env block — not a .env file.

3. Restart the IDE and test

   Ask the agent to run verify_zosmf_connection, then list_jobs.

{
  "mcpServers": {
    "mainframe": {
      "command": "npx",
      "args": ["-y", "@notharshhaa/mainframe-mcp-server"],
      "env": {
        "ZOSMF_HOST": "your-zosmf-host.internal",
        "ZOSMF_PORT": "443",
        "ZOSMF_TOKEN": "your-zosmf-token",
        "ZOSMF_TOKEN_TYPE": "LTPA2",
        "ZOSMF_REJECT_UNAUTHORIZED": "true",
        "SECURITY_READ_ONLY": "true",
        "SECURITY_AUDIT_LOGGING": "true"
      }
    }
  }
}

Option B — Run from source (VDI / internal Artifactory)

For environments that block public npm — clone the repo, install dependencies from your internal registry, build locally.

git clone https://github.com/NotHarshhaa/mainframe-mcp-server.git
cd mainframe-mcp-server
npm ci          # against your internal JFrog/npm mirror
npm run build
npm test          # unit tests, no mainframe required

{
  "mcpServers": {
    "mainframe": {
      "command": "node",
      "args": ["/absolute/path/to/mainframe-mcp-server/dist/index.js"],
      "env": {
        "ZOSMF_HOST": "your-zosmf-host.internal",
        "ZOSMF_PORT": "443",
        "ZOSMF_TOKEN": "your-zosmf-token",
        "ZOSMF_TOKEN_TYPE": "LTPA2"
      }
    }
  }
}

Required environment variables

Swipe horizontally to see all columns →

* Provide either user/password or a token.

Full reference: configuration.md · enterprise.md · deployment.md · mcp-client.example.json

Containers, Helm & supply-chain assurance

Releases publish an official non-root image to GHCR (signed with Sigstore keyless cosign, with SLSA provenance + SBOM attestations), the npm package ships with SLSA provenance, and every GitHub release carries SPDX + CycloneDX SBOMs plus a signed checksum manifest. A hardened Helm chart deploys the server read-only with dropped capabilities.

# Verify the image signature (keyless, bound to this repo's release workflow)
cosign verify ghcr.io/notharshhaa/mainframe-mcp-server:3.0.0 \
  --certificate-identity-regexp 'https://github.com/NotHarshhaa/mainframe-mcp-server/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Deploy on Kubernetes (non-root, read-only rootfs, policy + SIEM wired via values)
helm install mainframe-mcp helm/mainframe-mcp-server \
  --set zosmf.host=zosmf.example.com \
  --set zosmf.token="$ZOSMF_TOKEN" \
  --set policy.existingConfigMap=mcp-policy \
  --set security.auditOtlpUrl=http://otel-collector:4318

Enterprise deployment

Security and governance enforced at the MCP server layer — in addition to RACF and z/OSMF permissions.

Per-user identity — RACF sees who asked

Four mechanisms replace the shared service account. CICS and Db2 REST calls keep the service identity; z/OSMF tool calls run as the end user.

Swipe horizontally to see all columns →

Governed writes

Every gate is independent and operator-controlled — the agent cannot turn any of them off.

Swipe horizontally to see all columns →

Multi-environment, policy-as-code & RBAC, audit & SIEM, data protection

Four scale-up capabilities layer on top of the controls above — env-var rules always apply, and the policy file can only narrow them. Operator commands, JES2 hold/release, job cancel, IMS commands, CICS NEWCOPY and transaction disable are all gated writes: they respect SECURITY_READ_ONLY, role allow-lists, change tickets, and change windows like submit_jcl does. Full guide: enterprise.md · worked example: policy.example.yaml

Swipe horizontally to see all columns →

version: 1
defaults:
  role: viewer
  environment: dev
environments:
  prod:
    host: prod.zosmf.example.com
    password: ${env:ZOSMF_PROD_PASSWORD}
    readOnly: true                 # PROD is read-only
    allowedRoles: [operator, sre]
roles:
  viewer:
    tools: { allow: ["list_*", "get_*", "read_*", "search_*"] }
    readOnly: true
  operator:
    inherits: viewer
    readOnly: false                # explicit — parents are read-only
    datasets: { allow: ["PROD.**"] }
    changeTicketPattern: "CHG[0-9]{6}"
users:
  - username: BOB
    roles: [operator]
    environments: [dev, test, prod]
dataProtection:
  classifications:
    - name: pci-cardholder
      datasets: ["PROD.CARDS.**"]
      redact: [credit_card, ssn]
      maxLines: 200
      sample: { head: 100, tail: 25 }

Examples

Natural-language prompts map to MCP tool calls with structured responses.

Tool: analyze_job_failure({ jobId: "JOB01234" })

Job:     PAYJOB01 (JOB01234)
Status:  ABEND S806
Step:    STEP030 - LOADPGM
Reason:  Program load failure — module PAYRPTX not found
Fix:     Verify PAYRPTX is compiled and linked into the correct load library.

Tool: find_failed_jobs({ hours: 24 })

Tool: lookup_abend_code({ code: "S0C7" })

Tool: predict_batch_failures({ hours: 168 })

Tool: list_environments({})

  Name     │ Description        │ z/OSMF                     │ Writes    │ Roles
  default *│ Base connection    │ zosmf.example.com:443      │ read-only │ —
  dev      │ Development LPAR   │ dev.zosmf.example.com:443  │ read-write│ —
  prod     │ Production sysplex │ prod.zosmf.example.com:443 │ read-only │ operator

Tool: whoami({})
  Role: operator · Writes: permitted · Datasets: PROD.** · Ticket: CHG[0-9]{6}

Tool: read_dataset({ dsn: "PROD.CARDS.MASTER", environment: "prod" })

[masked content — PANs and SSNs redacted, first 100 + last 25 of 4,210 lines]

[data protection: 312 item(s) masked (credit_card, ssn);
 classification "pci-cardholder": sampled first 100 + last 25 of 4,210 lines]

Tool: submit_jcl({ jcl: "...", environment: "prod" })

Error [FORBIDDEN]: Tool "submit_jcl" is a write operation and
environment "prod" is read-only (policy: environments.prod.readOnly).

Tool: job_dependencies({ jobId: "JOB01234" })

1. SUMMARY
  Inputs (read):    PROD.PAY.TRANS, DEV.PAY.EXTRACT
  Updates:          PROD.PAY.MASTER
  Outputs:          PROD.PAY.RESULTS, PROD.PAY.LOG
  PROCs invoked:    PAYMERGE

Tool: issue_console_command({ command: "D A,L" })

1. RESPONSE  (console MCPDYN01)
  IEE114I 10.45.12 ACTIVE OPRUNIT=SYS1 …

[blocked with SECURITY_READ_ONLY=true unless explicitly enabled]

Tool: summarize_dump({ jobId: "JOB01234", ddName: "SYSUDUMP" })

Dump type: SYSUDUMP · System CC: S0C4 · User CC: 1234
Failing module: PAYRPTX offset 0000A2C6
Sections: REGISTERS, STORAGE, CONTROL BLOCKS