Mainframe MCP Server

A Model Context Protocol (MCP) server for IBM z/OS mainframes. It exposes the RSE (Remote System Explorer) REST API — read datasets and members (COBOL, JCL, PROC, copybooks), manage datasets, and submit and monitor jobs — as MCP tools.

Because it speaks the MCP protocol, the same server works in every MCP-compatible client: VS Code (GitHub Copilot), Cursor, Claude Desktop, Gemini CLI, and more. Configure it once per client.

It ships as a single pure-Python package (httpx, no PowerShell) exposing 31 tools, so it runs anywhere — Linux containers, macOS, Windows — and is publishable to PyPI and the MCP Registry.

Install (native package)

pip install mainframe-mcp        # or, from the mcp-server folder: pip install -e .

If public PyPI is blocked, use a mirror, e.g. pip install --index-url https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com mainframe-mcp

This installs a mainframe-mcp command that speaks MCP over stdio.

Configure (native)

Variable	Required	Default	Purpose
MF_HOSTNAME	yes	—	RSE API hostname
MF_PORT	no	443	RSE API port
MF_RSE_BASE_PATH	no	/rseapi/api/v1	API base path
MF_USERNAME	yes	—	TSO user id
MF_PASSWORD	yes	—	TSO password
MF_VERIFY_TLS	no	(off)	1 to verify the server certificate
MF_PDS_LOCATIONS	no	pds_locations.txt beside the module	Segment → dataset map for the get_* tools
MF_SEG_*	no	generic names	Per-site segment names (MF_SEG_COBOL, MF_SEG_COPYBOOK, MF_SEG_CT1, MF_SEG_JCL, MF_SEG_PROC, MF_SEG_JOBDOC) used in pds_locations.txt
MF_READ_ONLY	no	(unset)	1 disables all write/destructive tools
MF_ALLOWED_DSN	no	(unset)	Comma-separated dataset prefixes; write/destructive tools may only target these
MF_AUDIT_LOG	no	logs/audit.log	JSONL audit trail (sensitive fields redacted)

Copy pds_locations.sample.txt to pds_locations.txt and edit it for your site.

Client configuration

The native package installs a mainframe-mcp command. Point your client at it and pass the endpoint + credentials via env.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "mainframe": {
      "type": "stdio",
      "command": "mainframe-mcp",
      "env": {
        "MF_HOSTNAME": "your.host.example.com",
        "MF_USERNAME": "${input:mf_username}",
        "MF_PASSWORD": "${input:mf_password}"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "mainframe": {
      "command": "mainframe-mcp",
      "env": {
        "MF_HOSTNAME": "your.host.example.com",
        "MF_USERNAME": "you",
        "MF_PASSWORD": "..."
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mainframe": {
      "command": "mainframe-mcp",
      "env": {
        "MF_HOSTNAME": "your.host.example.com",
        "MF_USERNAME": "you",
        "MF_PASSWORD": "..."
      }
    }
  }
}

Available tools (31)

Retrieval: get_cobol, get_copybook, get_ct1, get_jcl, get_proc, get_job_docs, get_content, scan_source

Datasets: get_dataset_list, get_dataset_members, get_gdg_versions, search_seq_datasets, create_dataset, create_dataset_like, delete_dataset, rename_dataset, recall_dataset, copy_member, modify_module, upload_member

Jobs: submit_job, submit_jcl_string, get_job_status, get_job_steps, get_job_files, get_job_file_content, get_job_jcl, get_job_notification, get_spool_details, export_spool_to_dataset

TSO: run_tso_command

Architecture

Components:

Layer	File	Role
Transport / entry	server_native.py (main() → mcp.run())	Registers tools, speaks MCP over stdio
Safety layer	mcp_common.py	Intent annotations, read-only mode, confirm guards, scope allowlist, audit
RSE client	rse_client.py	Pure-Python httpx calls to the z/OS RSE REST API
Config	env + pds_locations.txt	Endpoint, credentials, segment → dataset map

What happens on a tool call:

sequenceDiagram
    participant C as MCP client
    participant S as server_native (FastMCP)
    participant W as mf_tool + _run
    participant SF as Safety (mcp_common)
    participant R as RSEClient (httpx)
    participant MF as RSE API
    C->>S: tools/call get_cobol(["PROG1"])
    S->>W: dispatch tool
    W->>SF: _dsn_allowed? / _needs_confirmation?
    alt blocked
        SF-->>C: {status:"error"|"needs_confirmation"}
    else allowed
        W->>W: _client() builds creds (MF_* env)
        W->>R: client.read_member(dsn)
        R->>MF: GET /datasets/{dsn}/content (Basic auth, TLS)
        MF-->>R: 200 + records
        R-->>W: unwrap_records()
        W->>SF: _audit(tool, args, "success", ms)
        W-->>C: {status:"success", data:{...}}
    end

Safety gates, in order:

1. Registration filter — MF_READ_ONLY=1 means the 10 write + 4 destructive tools are never registered (clients see only the 20 read tools).
2. Scope allowlist — MF_ALLOWED_DSN rejects out-of-scope datasets before any network call.
3. Confirm guard — destructive tools return needs_confirmation unless called with confirm=true.
4. Per-session credentials — creds come from MF_* env (or a per-session override); missing creds return a clean error.
5. Audit — every call appends a redacted JSONL line (tool, args, status, duration).

The safety layer (mcp_common.py) and RSE client (rse_client.py) are transport-agnostic, so the same tool bodies can be reused behind another transport (e.g. an HTTP/OAuth front end) without changing the mainframe logic.

Deploy

python -m build              # -> dist/mainframe_mcp-<ver>-py3-none-any.whl + .tar.gz
twine upload dist/*          # publish to PyPI

Then submit server.json to the MCP Registry. Users install with pip install mainframe-mcp and point their MCP client at the mainframe-mcp command with MF_HOSTNAME / MF_USERNAME / MF_PASSWORD set (see above).

Hosting over HTTP (Render, Cloud Run, ...)

To run as a hosted service instead of stdio, server_http.py serves the same tools over MCP streamable-HTTP at /mcp, guarded by a bearer token.

Local:

pip install -e ".[http]"
$env:MF_MCP_TOKEN="secret"; $env:MF_HOSTNAME="..."; $env:MF_USERNAME="..."; $env:MF_PASSWORD="..."
python server_http.py     # clients connect to http://localhost:8000/mcp
                          # with header: Authorization: Bearer secret

Render: a Dockerfile and render.yaml are included. In Render → New → Blueprint / Web Service from the (private) repo — it reads render.yaml, generates MF_MCP_TOKEN, and you set MF_HOSTNAME / MF_USERNAME / MF_PASSWORD in the dashboard. Endpoint: https://<your-app>.onrender.com/mcp.

Security: these tools can modify datasets and submit jobs. Keep MF_MCP_TOKEN set, serve only over HTTPS (Render terminates TLS), and prefer MF_READ_ONLY=1 (the render.yaml default). The host must also be able to reach your mainframe's RSE API — a public host cannot reach an internal z/OS system without a tunnel or VPN.