@notharshhaa/mainframe-mcp-server

mainframe-mcp-server

MCP Server for IBM z/OS using Zowe APIs

An enterprise-grade Model Context Protocol (MCP) server for IBM z/OS environments.
Bridges MCP-compatible AI agents with mainframe resources — jobs, datasets, USS, and operational diagnostics — using IBM Zowe SDK as the connectivity layer.

What it does

mainframe-mcp-server exposes z/OS capabilities as Model Context Protocol tools. An AI agent can list jobs, read datasets, inspect USS paths, submit JCL, and run operational diagnostics — without you writing Zowe CLI commands by hand.

Connectivity is handled by the IBM Zowe SDK over z/OSMF REST. This project adds the MCP tool layer, input validation, safety limits, and AI-friendly response formatting on top.

How it's different

	mainframe-mcp-server	Zowe CLI	Cloud MCP tools (K8s, AWS, GitHub…)
Interface	MCP tools for AI agents	Terminal commands	MCP tools for cloud-native stacks
z/OS coverage	Jobs, datasets, USS, diagnostics	Full Zowe command set	None
Workflow	Natural-language ops ("why did PAYJOB01 fail?")	Manual CLI scripting	N/A for mainframe
Output	Structured text tuned for LLM reasoning	Raw terminal output	N/A

This is not a replacement for Zowe CLI or IBM Z Open Editor — it is an MCP bridge so AI assistants can drive those same z/OSMF APIs.

Tools

Jobs

Tool	Description
list_jobs	List jobs by owner, prefix, or status
get_job_status	Status and return code for a job
get_job_output	Spool inventory or DD content
submit_jcl	Submit inline JCL
analyze_job_failure	Abend code, failing step, and suggested fix
get_job_jcl	Retrieve submitted JCL from job spool

Datasets

Tool	Description
list_datasets	List datasets matching an HLQ pattern
read_dataset	Read a sequential dataset or PDS member
search_dataset	Search datasets by pattern
search_members	Search or list PDS members
get_dataset_info	Catalog attributes without reading content

USS

Tool	Description
list_uss_directory	List a USS directory
read_uss_file	Read a USS file
search_uss_files	Search files under a USS path

Operations

Tool	Description
find_failed_jobs	Failed jobs in a time window
summarize_abends	Abend code breakdown across recent jobs
system_health_summary	Active, queued, and failed job snapshot
investigate_incident	Full incident bundle for a job
lookup_abend_code	Abend reference lookup (S0C7, S806, S222, S0C4, …)
verify_zosmf_connection	Test z/OSMF connectivity and auth
compare_jobs	Side-by-side comparison of two jobs
get_user_jobs_summary	Job counts by status for an owner

CICS

Tool	Description
list_cics_regions	List CICS regions via CMCI REST
get_cics_region_status	Status and attributes of a CICS region
list_cics_transactions	Transaction definitions in a region

Db2

Tool	Description
list_db2_subsystems	List Db2 locations via Db2 REST
search_db2_catalog	Search catalog tables and views

SMF / Security

Tool	Description
get_smf_metrics	SMF/RMF performance metrics snapshot
query_racf_audit	Query RACF audit records from a log source
security_posture_summary	Report active security controls and recommendations

Intelligence

Tool	Description
analyze_root_cause	Deep root-cause analysis with correlation and action items
predict_batch_failures	Predictive risk scoring for recurring batch failures

See docs/tools-reference.md for full input/output details.

Enterprise security

Yes — this server is designed for enterprise use, with controls big companies typically require. Security is enforced at the MCP server layer (in addition to RACF/z/OSMF permissions on the mainframe itself).

Control	Env variable	Purpose
Read-only mode	SECURITY_READ_ONLY=true	Blocks submit_jcl and other write tools
Tool allowlist	SECURITY_ALLOWED_TOOLS	Only permit specific tools (least privilege)
Tool blocklist	SECURITY_BLOCKED_TOOLS	Explicitly deny dangerous tools
Dataset boundaries	SECURITY_ALLOWED_DATASET_PATTERNS	Restrict dataset access by HLQ pattern
USS boundaries	SECURITY_ALLOWED_USS_PATHS	Restrict USS paths by prefix
Audit logging	SECURITY_AUDIT_LOGGING=true	Log every tool call (credentials redacted)
JCL size limit	SECURITY_MAX_JCL_BYTES	Cap inline JCL submit size
TLS verification	ZOSMF_REJECT_UNAUTHORIZED=true	Enforce certificate validation

Use security_posture_summary to inspect which controls are active and get hardening recommendations.

Important: Enterprise deployment also requires:

• A dedicated service account on z/OS with least-privilege RACF profiles
• Secrets in a vault (not plain env vars in production)
• Network restrictions (z/OSMF behind API gateway / VPN)
• SSE transport placed behind auth proxy if exposed beyond localhost

The mainframe still enforces the final authorization — this server adds guardrails so AI agents cannot exceed configured boundaries.

Phase 3 capabilities (require optional enterprise configuration):

• CICS region tools — CMCI REST integration (CMCI_CONTEXT, CMCI_HOST, CMCI_PORT)
• Db2 catalog tools — Db2 REST SQL queries (DB2_LOCATION, DB2_HOST, DB2_PORT)
• SMF metrics exposure — z/OSMF RMF and/or SMF_SUMMARY_DATASET
• RACF audit integration — parse audit logs from RACF_AUDIT_USS_PATH or RACF_AUDIT_DATASET
• AI-assisted root cause analysis — analyze_root_cause with confidence scoring and correlated incidents
• Predictive batch failure detection — predict_batch_failures with risk levels and trends

Operational intelligence

Phase 2 capabilities built into the server:

• USS tools — list, read, and search USS paths
• investigate_incident — status, root-cause analysis, spool inventory, and diagnostic excerpt in one call
• system_health_summary — HEALTHY / DEGRADED / CRITICAL snapshot with top abend codes
• Abend code lookup — curated reference for common system and user abends via lookup_abend_code
• Structured responses — numbered sections and tables designed for AI agent parsing
• Integration tests — optional sandbox suite (RUN_INTEGRATION=1 npm run test:integration)

Quick start

Requirements: Node.js 18+, a reachable z/OSMF endpoint, and valid z/OS credentials.

Install via npm

npx -y @notharshhaa/mainframe-mcp-server

When you add this server in your IDE (Cursor, VS Code, Claude Desktop, etc.), the installer prompts for connection settings (driven by server.json). Those values are stored in your MCP config file — not in a .env file.

Example MCP config (see also config/mcp-client.example.json):

{
  "mcpServers": {
    "mainframe": {
      "command": "npx",
      "args": ["-y", "@notharshhaa/mainframe-mcp-server"],
      "env": {
        "ZOSMF_HOST": "your-zosmf-host.internal",
        "ZOSMF_PORT": "443",
        "ZOSMF_USER": "your-username",
        "ZOSMF_PASSWORD": "your-password"
      }
    }
  }
}

Run from source

git clone https://github.com/NotHarshhaa/mainframe-mcp-server.git
cd mainframe-mcp-server
npm install
npm run build

Point your IDE at dist/index.js and set env in MCP config (copy from config/mcp-client.example.json), or export variables in your shell before npm start.

Environment variables

Variable	Required	Description
ZOSMF_HOST	yes	z/OSMF hostname
ZOSMF_USER / ZOSMF_PASSWORD	yes*	Basic auth credentials
ZOSMF_TOKEN	yes*	Token auth (alternative to user/password)
ZOSMF_PORT	no	HTTPS port (default 443)
ZOSMF_REJECT_UNAUTHORIZED	no	TLS verification (default true)

* Provide either user/password or a token.

Full configuration reference: docs/configuration.md

Examples

Why did a job fail?

User:  Why did PAYJOB01 fail?
Agent: 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.

Failed jobs in the last 24 hours

User:  Show me all failed jobs from the last 24 hours
Agent: find_failed_jobs({ hours: 24 })

Read a dataset member

User:  Show me SYS1.PROCLIB(IKJEFT01)
Agent: read_dataset({ dsn: "SYS1.PROCLIB", member: "IKJEFT01" })

What does abend S0C7 mean?

User:  What is abend S0C7?
Agent: lookup_abend_code({ code: "S0C7" })

Predict which batch jobs might fail next

User:  Which batch jobs are at risk of failing?
Agent: predict_batch_failures({ hours: 168 })

Documentation

• Website (GitHub Pages) — overview, tools, setup, enterprise guide
• Configuration — all environment variables
• Tools reference — inputs, outputs, and error codes
• Deployment — stdio vs SSE transport

License

MIT — see LICENSE