🖥️ IBM i (AS/400) MCP Server

An MCP (Model Context Protocol) server that enables AI agents to interact with IBM i (AS/400) systems for RPA automation. Provides 37 tools across three transport layers.

✨ What This Does

Gives any MCP-compatible AI agent (Amazon Quick, Claude Desktop, etc.) the ability to:

• 🖥️ Navigate 5250 green screens — Login, select menu options, fill fields, press F-keys

• ⚡ Execute CL commands via SSH — WRKACTJOB, DSPLIB, CALL PGM, and more

• 🗄️ Query DB2/400 via ODBC — SQL queries, program calls, IBM i Services

• 📋 Manage jobs, spool files, IFS, data queues, and message queues

Related MCP server: IBM i MCP Server

Architecture

┌─────────────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│   AI Agent          │     │   IBM i MCP Server           │     │   IBM i      │
│   (MCP Client)      │────▶│   (stdio transport)          │────▶│   (AS/400)   │
│                     │     │                              │     │              │
│   Tools:            │     │   ┌────────────────────────┐ │     │   ┌────────┐ │
│   • ibmi_connect_*  │     │   │ TN5250 Session Manager │─┼─────┼──▶│ 5250   │ │
│   • ibmi_send_keys  │     │   ├────────────────────────┤ │     │   ├────────┤ │
│   • ibmi_read_screen│     │   │ SSH Session Manager    │─┼─────┼──▶│ SSHD   │ │
│   • ibmi_run_cl     │     │   ├────────────────────────┤ │     │   ├────────┤ │
│   • ibmi_query      │     │   │ ODBC Connection Pool   │─┼─────┼──▶│ DB2    │ │
│   • ...37 tools     │     │   └────────────────────────┘ │     │   └────────┘ │
└─────────────────────┘     └──────────────────────────────┘     └──────────────┘

🚀 Quick Start

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/ibmi-mcp-server.git
cd ibmi-mcp-server

2. Install dependencies

Windows:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Or just run the setup script:

# Windows
setup.bat

# Linux/macOS
chmod +x setup.sh && ./setup.sh

3. Configure

Copy the example environment file and fill in your IBM i connection details:

cp .env.example .env

Edit .env:

IBMI_HOST=your-ibmi-host.example.com
IBMI_PORT=23
IBMI_SSH_PORT=22
IBMI_USER=YOUR_USER
IBMI_PASSWORD=YOUR_PASSWORD

4. Register with your MCP client

Amazon Quick

Go to Settings → Capabilities → Connections → Add MCP Server and paste:

{
  "name": "IBM i (AS/400)",
  "command": "/path/to/ibmi-mcp-server/.venv/bin/python3",
  "args": ["/path/to/ibmi-mcp-server/server.py"],
  "env": {
    "IBMI_HOST": "your-host.example.com",
    "IBMI_USER": "YOUR_USER",
    "IBMI_PASSWORD": "YOUR_PASSWORD"
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ibmi": {
      "command": "/path/to/ibmi-mcp-server/.venv/bin/python3",
      "args": ["/path/to/ibmi-mcp-server/server.py"],
      "env": {
        "IBMI_HOST": "your-host.example.com",
        "IBMI_USER": "YOUR_USER",
        "IBMI_PASSWORD": "YOUR_PASSWORD"
      }
    }
  }
}

5. Test

Once registered, ask your AI agent:

"Connect to IBM i and show me the main menu"

📋 Tools Reference

5250 Terminal (Interactive Green-Screen)

SSH/Command (CL & Shell)

ODBC/SQL (Database & Programs)

Spool File Management

Job Monitoring & Control

Data Queue Operations

IFS File Operations

Message Queue Operations

Object Management

Utility

🔒 Security

Command Blocklist

By default, these dangerous CL commands are blocked:

• PWRDWNSYS — Power Down System

• DLTLIB — Delete Library

• RSTLIB — Restore Library

• INZSYS — Initialize System

• ENDSYS — End System

• ENDSBS *ALL — End All Subsystems

Configure via IBMI_COMMAND_BLOCKLIST environment variable.

Best Practices

1. Use a dedicated user profile with minimal authority for automation

2. Set command blocklists to prevent destructive operations

3. Enable audit journaling (QAUDJRN) on the IBM i for traceability

4. Use SSL/TLS when possible (port 992 for 5250, key-based auth for SSH)

5. Never store credentials in code — use environment variables or a secrets manager

6. Never commit .env — it's in .gitignore by default

🧪 Testing with Mock Server

A mock AS/400 telnet server is included for testing without a real IBM i system:

python mock_as400_server.py --port 2323

Connect to it with:

IBMI_HOST=localhost
IBMI_PORT=2323
IBMI_USER=QSECOFR
IBMI_PASSWORD=QSECOFR

Available mock users:

📁 Project Structure

ibmi-mcp-server/
├── server.py              ← Main MCP server (auto-detects plain telnet vs TN5250)
├── tools_extended.py      ← Extended tool definitions (spool, jobs, IFS, etc.)
├── handlers_extended.py   ← Extended tool implementations
├── mock_as400_server.py   ← Mock server for testing (optional)
├── requirements.txt       ← Python dependencies
├── .env.example           ← Configuration template (safe to commit)
├── .gitignore             ← Excludes .env, .venv, __pycache__
├── setup.bat              ← Windows setup script
├── setup.sh               ← Linux/macOS setup script
└── LICENSE                ← MIT License

🤝 Contributing

Contributions welcome! Areas that need work:

• Full TN5250E protocol implementation (currently supports plain telnet + basic TN5250)

• Connection pooling for multi-session support

• Screen signature registry for automatic screen identification

• JT400 (Java Toolkit) integration via JPype bridge

• Integration tests with a real IBM i partition

• Docker container for easy deployment

📖 How It Works

The server auto-detects the connection type:

1. Plain Telnet — If the IBM i (or mock) sends UTF-8 text on connect, the server switches to line-based I/O mode (sends \r\n for ENTER, reads text responses)

2. Binary TN5250 — If the server starts with IAC bytes (0xFF), full TN5250 negotiation and EBCDIC encoding is used

This makes it compatible with both real IBM i systems and simple telnet-based mock servers.

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

Built with research from:

• RFC 1205 — 5250 Telnet Interface

• IBM i Access ODBC

• p5250 Python Library

• JT400 (IBM Toolbox for Java)

• QSYS2 SQL Services

• MCP Specification