ibmi-agent-kit
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ibmi-agent-kit
One MCP server for IBM i. It gives an AI agent 5250 green screens, source members, and SQL
and CL, all through the signed-on user's own IBM i profile. Each user signs on as themselves,
so IBM i object authority stays the real boundary. An execution guard catches dangerous mistakes
in run_script and verb_run before they run; see Safety.
The split of work: users sign on as themselves; what a company knows about its system (procedures, naming, standards) lives in Claude skills in the company's private repo, and the MCP holds none of it; the MCP executes and the guard checks.
Packages
Package | What |
profile loader and the SQL transport type | |
execution guard: classifier, CL command table, policy | |
5250 engine | |
source and SQL engine | |
the stdio MCP server, |
Related MCP server: IBM i MCP Server
Install
From this repo, with Node 20 or newer. Nothing is published to npm.
git clone https://github.com/klintravis/ibmi-agent-kit
cd ibmi-agent-kit
npm ci && npm run check
claude mcp add ibmi-agent-kit -- node <abs path>/packages/server/dist/index.jsUse the absolute path to this checkout in place of <abs path>. Restart Claude Code or run
/mcp. The server speaks MCP on stdio and exits when the client closes it.
First sign-on in your browser. With no profile, list_servers offers a one-time page on 127.0.0.1 in your own browser (host, user, password); a store profile with no stored password is offered one too. The password goes only to the OS credential store, never to Claude or the IBM i. It is not tried at submit: ask Claude to try again, and each wrong password is a real sign-on attempt toward QMAXSIGN. In a headless, remote or no-Secret-Service session, use setup. See Sign-on page.
Or create a profile and test it from the terminal (the route for those sessions). Run this yourself in a real terminal (PowerShell, Windows Terminal, macOS Terminal or a Linux shell), not through Claude:
node <abs path>/packages/server/dist/index.js setup [name]It asks for the host, the user, where the password comes from and an optional policy file, writes the profile, then connects and prints OK or why it failed. See setup command.
Passwords are not kept in the profile. At the "password source" prompt press Enter for the OS credential store (Windows Credential Manager, macOS Keychain, Linux Secret Service) and type the password once, hidden. Or type a helper command (for example your company's secret manager's CLI) that prints the password; the helper is run for every sign-on, and it is refused when the profile file is inside a git work tree. The command you type is shown on screen and stored as typed, so it must hold no secret. To rotate a password, change it on the IBM i, then run node <abs path>/packages/server/dist/index.js credential set <profile> (a helper: change the secret where it reads it). There is no credential get, on purpose. Limits:
A password the IBM i rejected is not sent again by the same server process, so a stale password costs one sign-on attempt, not a locked profile. The record is per process and per user and host: several clients, several machines or a
setuprun each send it once, and together can still reach the IBM i limit (QMAXSIGN).An
IBMI_PASSWORDline in an existing profile still works, with a warning on standard error that names the file. Runsetupto move it to the store.Anyone who can run commands as you can read your store entry or run your helper. This keeps passwords out of files, not out of reach of your own account.
Details, helper rules and a Windows Credential Manager example: Passwords.
In a company config repo (one the ibmi-kit-config skill made; layout in templates/company-repo), follow that repo's README, Get started: clone it, run setup inside the clone, set IBMI_KIT_HOME to this checkout, run claude there. setup then takes the host, partition and other settings from the repo's profile skeleton and the policy path from the clone, and asks only your user and where your password comes from (each person chooses; the repo never supplies one). Its .mcp.json registers the server, so claude mcp add is not needed. See In a company config repo.
Try it: docs/demo.md is a quick-start demo you can run against your own IBM i (or guided: /demo).
Tools
Pass server (a name from list_servers) to pick which IBM i; omit it for the default.
Tool | Package | What it does | Read-only / changes / runs code |
| screen | Replays Markdown screen regression tests against a program | changes; runs code |
| screen | Types into fields and presses keys on the 5250 screen | changes; runs code |
| screen | Returns the current screen | read-only |
| screen | Signs off and closes a 5250 session | changes |
| screen | Signs on and opens a 5250 session, optionally starting a program | changes; runs code |
| server | Lists configured servers and open sessions | read-only |
| server | Shows what the execution policy would decide for a script, or for every statement a verb would send, without running it | read-only |
| server | Runs SQL and CL after the execution policy decides every statement | changes; runs code |
| server | Lists the verbs (named, parameterised procedures in YAML files) by layer, with tags, parameters and overrides | read-only |
| server | Runs a verb, or every verb with a tag, after the execution policy decides every statement | changes; runs code |
| source | Compiles a source member and parses the compile messages | changes; runs code |
| source | Lists libraries | read-only |
| source | Lists the members of a source file | read-only |
| source | Lists source files in a library | read-only |
| source | Shows or changes the job's library list for the session | changes |
| source | Downloads a source member to a local editable copy | read-only |
| source | Runs a SQL select | read-only |
| source | Searches source members for text | read-only |
| source | Uploads a local file to a source member | changes |
The last column is each tool's MCP annotation (read-only or destructive) plus whether it runs a program or command. Each package README has the arguments and details.
Profiles
A profile is one .env file naming one IBM i. Folders, first match wins:
IBMI_KIT_CONFIG_DIR(or the olderIBMI_MCP_CONFIG_DIR), set on the MCP registration~/.ibmi-agent-kit~/.ibm-i-servers
.env is the server called default; .env.<name> is the server called <name>;
.env.example is never a server, and neither is .env.default (the default is .env), a
.env. with no name, a leftover ending .bak, .orig or ~, or anything that is not a regular
file. A server argument must match a listed name exactly. One
file supplies the whole profile; files are never merged, and nothing from them is loaded into
the process environment. setup [name] writes or updates one for you in the first folder
(setup command). To write one by hand, copy
packages/source/.env.example or packages/screen/.env.example. list_servers shows the folders
searched and the open sessions.
Protected settings are read from the profile file only, never from the environment, so an MCP
registration's env cannot override them (IBMI_KIT_CONFIG_DIR does choose which profile folder
is read): IBMI_HOST, IBMI_USER, IBMI_PASSWORD, IBMI_PASSWORD_COMMAND, IBMI_PASSWORD_STORE,
IBMI_PARTITION, IBMI_KIT_POLICY (absolute path), IBMI_KIT_VERBS (absolute folders, separated by ; on Windows and :
elsewhere), IBMI_SQL_TRANSPORT, IBMI_RESTRICTED, IBMI_ALLOWED_CL, IBMI_BLOCKED_CL,
IBMI_BLOCKED_TABLES, IBMI_READ_ONLY, IBMI_5250_TLS_INSECURE, IBMI_5250_REPORT_DIR, IBMI_MAPEPIRE_CA,
IBMI_MAPEPIRE_JAR, and every IBMI_*_PORT
(IBMI_SSH_PORT, IBMI_MAPEPIRE_PORT, IBMI_5250_PORT, IBMI_5250_VIEWER_PORT). Other
IBMI_* settings may still come from the environment when the file omits them.
SQL transports
IBMI_SQL_TRANSPORT picks how SQL and CL reach the IBM i. Default ssh.
Transport | Needs on the IBM i | Notes |
| SSH access for the user, a Java runtime, and write access to their home folder | Uploads the bundled Mapepire jar into the user's home and runs it in the user's job over that SSH session. No port to open, but uploading a jar may need your security team's approval. |
| A Mapepire server run by an administrator, listening on | No SSH and no upload. The server must already be installed and started; the kit does not install it. If its certificate is not signed by a public CA, set |
Some source tools (for example search_source) need more on the box; see
packages/source/README.md.
PUB400
PUB400 is a free public IBM i for learning. For the kit:
5250 is on port 992 with TLS:
IBMI_5250_PORT=992.SSH is on 2222, not 22:
IBMI_SSH_PORT=2222.Never create objects in
QGPL; use your own library.Non-commercial use only. Keep sessions few and close them when done.
Safety
run_script runs every SQL statement and CL command through the execution guard: each is
classified, matched against a policy file (roles, environments, partitions, rules) and allowed,
confirmed with the user, or denied before anything is sent. verb_run does the same for every
statement of a verb, its nested verbs and its cleanup, and for every verb of a tag suite, decided
as one script before the first is sent; a verb runs with the signed-on user's rules, so sharing
one grants nothing. policy_check makes the same decisions but only reports them. With no
policy file the built-in policy (observe mode, one allow rule) logs every decision and runs
everything except danger operations and unqualified changes (a write with no library), which it
still denies (see Policy).
The source tools are decided the same way before they act: run_sql, read_source_member and
search_source as reads of their table, source file or library; upload_source_member as a write
to the member's source file; manage_library_list changes as liblist on each library (show is
not decided); compile_member from its final command, command override included, plus the
member's statements, read at decision time, for an SQL member or RUNSQLSTM. A member whose read
is denied is never fetched; one whose read a rule asks to confirm is fetched only after a yes, so
that prompt shows none of its lines. A denied call sends nothing to the IBM i, and the source
engine's own checks still apply.
compile_member's default target *CURLIB is decided as the job's current library; with none, the
compile is denied as unqualified, so pass targetLibrary.
The 5250 tools are decided too. Before screen_do or run_tests sends a key that carries field
data (any key but F3, F12, Clear and Attn), the text on the screen's command line at that moment,
typed or brought back with F9, is decided as a CL command; a denied one is not sent. F4 with a
command on the line is denied in every mode, observe included, like a ? prompt: the prompter's
values are typed later on a screen with no command line, where the guard does not see them.
session_open reads the sign-on screen's System name (which then places the box in its partition),
then decides its program (or the profile's IBMI_5250_PROGRAM) as a call and its library (or
IBMI_5250_CURLIB) as liblist before typing them; a deny signs nothing on. menu is not
decided. The session's own sign-on, recovery and sign-off keys are never decided. A command line
runs in the 5250 job, which the guard cannot see into, so there *CURLIB is decided as
unqualified and a write through an alias or view in QTEMP is denied. A menu option (digits only)
typed on a ===> line is not decided; any other text there that is not a command is denied. Each
decision reads the user's identity over SQL; when that lookup fails (a profile with no working SQL
connection, say), the profile's user decides with default_role, the run log says the lookup
failed, and the next decision tries the lookup again.
These decisions, and those of run_script and verb_run, go to a local run log. Read packages/guard/README.md for how it works and
docs/policy.md for the policy file, and docs/verbs.md for verbs.
Limits, stated plainly: the guard sees only the text it is given, not what called programs or
triggers do, nor menu options, prompted fields or options typed on a list screen; IBM i authority
remains the real boundary. The source tools also use IBMI_READ_ONLY, IBMI_BLOCKED_TABLES and
IBMI_BLOCKED_CL (compile commands only). The 5250 tools also use IBMI_RESTRICTED (an allowlist, on by default), IBMI_ALLOWED_CL and
IBMI_BLOCKED_CL (the last applies only when restricted is off); they ignore IBMI_READ_ONLY.
Those three check text as it is typed into a command line and again, before the guard, on what the
line holds when the key is pressed, so a command brought back with F9 meets both.
Policy
The guard's rules are one YAML file, set per profile with IBMI_KIT_POLICY (an absolute path):
partitions, environments, roles and first-match rules over the classes read, write, ddl,
compile, call, liblist, promote and your own. Start in mode: observe (decide and log,
block nothing extra) and switch partitions to enforce one at a time; policy_check, policy test
and policy replay check a policy before you trust it. A policy lives in your company repo and the
agent must not be able to edit it. Field reference, command tables, roles, the run log and stated
limits are in docs/policy.md; a complete example with tests is
examples/three-partitions.yaml.
Words
"Statements and commands" means SQL statements and CL commands. A "verb" is a named, parameterised procedure (setup, steps, expectations, cleanup) that a person or a project writes as a YAML file; see docs/verbs.md.
Built on
packages/screen and packages/source are a hard fork of two Apache-2.0 servers by
SH4RKKK (Saman): https://github.com/SH4RKKK/ibm-i-5250-mcp and
https://github.com/SH4RKKK/ibm-i-source-mcp. Their license and notices are kept; changed
files carry a modification line. Apache-2.0, see LICENSE and NOTICE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Connect AI agents to financial institution origination, analytics, and compliance workflows.
Query your team's AI coding history and act on HypAware recommendations from any MCP client.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with IBM i systems through SQL tools and commands, supporting secure authentication, system monitoring, and database operations via the Model Context Protocol.93Apache 2.0- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with IBM i systems through the Model Context Protocol, providing secure SQL-based access to Db2 for i databases for querying, monitoring, and executing operations.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to securely interact with IBM i (AS/400) systems via ODBC, supporting SQL queries, CL commands, source code reading, compilation, and spoolfile analysis.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with IBM i (AS/400) systems for RPA automation via 37 tools for 5250 navigation, CL commands, DB2 queries, and system management.MIT