Skip to main content

Zcrafter

Zcrafter Bridge: MCP server for IBM z/OS mainframes

Give AI Agents real access to your mainframe and keep it from changing anything you haven't approved.

Zcrafter Bridge is an open-source Model Context Protocol (MCP) server for IBM z/OS. It lets AI agents such as Claude Code, Codex, Cursor, GitHub Copilot in VS Code and Gemini CLI work on a mainframe: datasets and PDS members, COBOL and JCL, batch jobs and spool, z/OS UNIX files, TSO commands and the operator console.

  • 48 tools over z/OSMF and the Zowe SDK. Nothing is installed on the mainframe.
  • A person approves every change. The agent cannot approve its own work, and an approval covers only the steps it lists.
  • One line to install, on macOS, Linux and Windows.
Screenshot 2026-09-24 at 11 58 01 PM

What's an MCP server?

MCP is how AI Agents talks to outside systems. An MCP server hands AI a set of tools it can call. Bridge is an MCP server whose tools are your mainframe - datasets, members, z/OS UNIX files, jobs, spool, TSO and the operator console, with an approval gate in front of anything that changes the system.

Install it once, point your AI client at it, then just talk.


Install

One line, on macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/ZcrafterAI/Bridge/main/install.sh | sh

Or directly with uv, on any system including Windows:

uv tool install git+https://github.com/ZcrafterAI/Bridge

Either way you get one command, zcrafter-bridge. It needs Python 3.11 or newer, which uv fetches for you. It no longer needs Node.

What the installer does: it finds uv (or installs it for your user), then runs uv tool install, which puts Bridge and its dependencies in a folder of their own under your home directory. It uses no sudo and changes nothing system-wide. You can read it first: install.sh. To remove Bridge: uv tool uninstall zcrafter-bridge.

Connect your AI client

Client How
Claude Code claude mcp add zcrafter-bridge -- zcrafter-bridge
Codex codex mcp add zcrafter-bridge -- zcrafter-bridge
Claude Desktop, Cursor, Gemini CLI Add the JSON below to the client's MCP settings
VS Code The same entry under "servers" in .vscode/mcp.json
{
  "mcpServers": {
    "zcrafter-bridge": { "command": "zcrafter-bridge" }
  }
}

Claude Code users can also install the skill that teaches the agent the approval flow:

zcrafter-bridge install-skill

Connect your mainframe

Bridge signs in to z/OSMF as you. It looks for your sign-in in this order:

  1. Environment variables: ZOWE_OPT_HOST, ZOWE_OPT_USER, ZOWE_OPT_PASSWORD (and optionally ZOWE_OPT_PORT, ZOWE_OPT_REJECT_UNAUTHORIZED, ZOWE_OPT_BASE_PATH). These are Zowe CLI's own names.
  2. Your Zowe profile: ~/.zowe/zowe.config.json, with the password read from your operating system's keychain, where zowe config secure put it. Test the profile with zowe zosmf check status.

No password is stored by Bridge, and none is ever sent to the AI model.


How the gate works

Reading is free. Listing datasets, reading members, checking jobs, searching spool — no approval needed.

Changing anything is gated. Before an agent can write a member, submit a job, run a command or delete a dataset, it must:

  1. Open a request
  2. Write a spec (what changes and why) and get your yes
  3. Write a plan that lists every change as a step, and get your yes

Only you can say yes. The agent can ask for an approval. It cannot give one. Bridge asks you directly, outside the agent's reach:

  • in your AI client's own prompt, when the client has one, or
  • on a page Bridge opens in your browser, on your machine only, or
  • in a terminal, with zcrafter-bridge approve, on a machine with no browser.

The page's address carries a one-time token the agent never sees, so an agent that can browse still cannot press Approve.

The approval page: what was asked, the plan, and each change it allows

Your yes covers the listed steps and nothing else. Each step names one tool and its target, for example member.write on PAY.TEST.COBOL(PAYCALC). After approval a change runs only if it matches a step, and each step runs once unless the plan says more. A command step fixes the exact command. A step can also fix the exact content, diff or JCL, and then that is what must be sent.

The agent tries It gets
A change before you approved PLAN_NOT_APPROVED
To approve its own plan WAITING_FOR_PERSON, and you get asked
A change the plan did not list STEP_NOT_IN_PLAN
A change to a protected dataset PROTECTED_DATASET

Editing the spec after approval un-approves the plan too. Every change is logged with its inputs; passwords are redacted, diffs are hashed.


Tools

48 tools. The ones in italics change the system, so they need an approved plan step.

Datasets list, info, read, write, create, create like, delete, rename, copy, recall, migrate
Members list, read, search, write, patch, delete, rename
z/OS UNIX files list, read, write, create, delete, rename, chmod
Jobs list, status, steps, failed jobs, wait, JCL, spool, output, submit, cancel, purge, hold, release, change class
TSO tso.query for read-only commands (LISTCAT, LISTDS, LISTUSER...), tso.command for anything else
Operator console console.command
System list systems, verify connection, list profiles, search the tool catalog

job.steps shows which step of a job failed, and job.failed lists the jobs that ended badly, so an agent can start from the failure instead of reading every log.

Large reads (member.read, dataset.read, job.output, job.spool.read) accept searchText, maxLines and regex — so Claude finds one line in a 40,000-line job log instead of pulling the whole thing into context.


Configuration

Copy .env.example to .env to change defaults.

Variable Default
MAINFRAME_WORKFLOW_ZOWE_PROFILE default Which Zowe profile to use
MAINFRAME_WORKFLOW_DB_PATH ~/.zcrafter-bridge/state.db Where requests are stored
MAINFRAME_WORKFLOW_IDLE_DAYS 14 Abandon untouched requests after
MAINFRAME_WORKFLOW_RETENTION_DAYS 90 Archive finished requests after
MAINFRAME_WORKFLOW_APIML_BASE_PATH — Set if z/OSMF is behind API ML
MAINFRAME_WORKFLOW_APPROVAL auto How you approve: auto (your AI client's prompt, else a browser page), prompt, browser, terminal
MAINFRAME_WORKFLOW_APPROVAL_WAIT_SECONDS 60 How long one approval call waits for you before telling the agent to ask again
MAINFRAME_WORKFLOW_READ_ONLY false true offers no tool that changes anything
MAINFRAME_WORKFLOW_PROTECTED_DATASETS — Patterns the dataset and member tools may never write to, e.g. SYS1.**,*.PROD.**
MAINFRAME_WORKFLOW_TSO_ACCOUNT ACCT TSO account number, used on z/OSMF without the one-request TSO interface

MAINFRAME_WORKFLOW_APPROVAL=unsafe-agent turns the person off: the agent's own call counts as approval. It exists for automated runs against throwaway systems. Do not use it on a mainframe you care about.


Troubleshooting

Zowe config not found — Bridge reads ~/.zowe/zowe.config.json. Run zowe config list to confirm you have one, or set ZOWE_OPT_HOST, ZOWE_OPT_USER and ZOWE_OPT_PASSWORD.

z/OSMF profile "default" not found — your profile has another name. Run zowe config list profiles, then set MAINFRAME_WORKFLOW_ZOWE_PROFILE in .env.

...is missing host, user or password — credentials aren't in your OS keychain. Re-run zowe config secure.

could not read the OS keychain — the machine has no keychain Bridge can open (common on servers and in containers). Use the ZOWE_OPT_* variables there.

Claude says a tool isn't allowed — approve it when prompted, or check claude mcp list.

The agent says an approval is waiting but nothing opened — the address is printed in the server's log (stderr), or run zcrafter-bridge approve in a terminal.

STEP_NOT_IN_PLAN — the agent tried a change you did not approve. It has to write a new plan revision that lists it and ask you again.

tso.command or console.command answers 401 or 403 — your user ID needs TSO or EMCS console authority on the mainframe. Bridge cannot grant it.


Development

git clone https://github.com/ZcrafterAI/Bridge.git && cd Bridge
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                               # 185 tests, no mainframe needed
python -m mainframe_workflow_mcp.cli                 # run from source

credential-resolver/ is the older Node helper for reading the Zowe keychain. Bridge reads the keychain itself now and only falls back to the helper if you have built it (cd credential-resolver && npm install && npm run build).

Architecture notes: docs/architecture.md. The tool catalog lives in mainframe_workflow_mcp/toolbox/ and the z/OSMF calls in mainframe_workflow_mcp/clients/.


Questions

What is Zcrafter Bridge? An MCP server that connects AI agents to an IBM z/OS mainframe through z/OSMF, with a person approving every change.

Which AI clients work with it? Any client that speaks MCP over stdio: Claude Code, Claude Desktop, OpenAI Codex, Cursor, VS Code with GitHub Copilot, Gemini CLI and others.

What does it need on the mainframe? z/OSMF switched on and a user ID. Nothing is installed on z/OS. It uses your existing Zowe profile, or three environment variables.

Can the AI change my mainframe without asking? No. Reading needs no approval. Any change needs a plan you approve, on a channel the agent cannot reach, and only the changes that plan lists can run.

Does it work with COBOL and JCL? Yes. It reads and edits members, applies diffs, submits JCL, waits for the job, reads the output, and can show which step failed and with what code.

How is it different from Zowe CLI? Zowe CLI is a command line for people. Bridge gives an AI agent the same z/OSMF operations as tools, built on the Zowe SDK, and puts an approval gate and an audit log in front of anything that changes the system.

Whose permissions does it use? Yours. Bridge signs in as your user ID, so your site's security rules (RACF, ACF2 or Top Secret) apply to everything the agent does.

Is it free? Yes, MIT licensed.

Who makes it? Zcrafter, which also makes Cobots, a desktop app where a team of AI agents works on your mainframe.


MIT licensed. Contributions welcome — see CONTRIBUTING.md.

Metadata

Release files for zcrafter-bridge 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zcrafter-bridge 0.3.0
File Size Uploaded Provenance Actions
zcrafter_bridge-0.3.0.tar.gz 458.4 kB With provenance Details for zcrafter_bridge-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zcrafter-bridge 0.3.0
File Interpreter ABI Platform Actions
zcrafter_bridge-0.3.0-py3-none-any.whl Python 3 none any Details for zcrafter_bridge-0.3.0-py3-none-any.whl

Total release size: 525.5 kB

Release files / zcrafter_bridge-0.3.0.tar.gz

Download URL zcrafter_bridge-0.3.0.tar.gz
Size 458.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5a80f9ca78f8ff8db954bf892a3b9043ec6755a4b365ef66e04e83f9c79de744
BLAKE2b-256 checksum
How to use checksums
44da98db9f1eac2257dc44c053bc8a4d3de5d80dad2ef7dbae0f0dac5942dc1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / zcrafter_bridge-0.3.0-py3-none-any.whl

Download URL zcrafter_bridge-0.3.0-py3-none-any.whl
Size 67.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bca7eace44ac10130f82b684234009f411fad387b557b374f1d679e87218833b
BLAKE2b-256 checksum
How to use checksums
0eae4f4f1515b8f307dde548b4db4f6da369b7568de31ea6cd8a16ec63410d8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for zcrafter-bridge 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zcrafter_bridge-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page