# 🖥️ IBM i (AS/400) MCP Server

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io/)

## ✨ 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**

## 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

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

### 2. Install dependencies

**Windows:**
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

**Linux / macOS:**
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Or just run the setup script:
```bash
# 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:

```bash
cp .env.example .env
```

Edit `.env`:
```ini
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:

```json
{
  "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`:

```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)

| Tool | Description |
|------|-------------|
| `ibmi_connect_5250` | Connect via TN5250 (auto-detects plain telnet vs binary protocol) |
| `ibmi_login` | Login with user/password on the sign-on screen |
| `ibmi_send_keys` | Send text + function key (ENTER, F1-F24, PAGEUP, etc.) |
| `ibmi_read_screen` | Read current screen (raw/structured/fields) |
| `ibmi_set_cursor` | Move cursor to row/col position |
| `ibmi_disconnect_5250` | Close the terminal session |

### SSH/Command (CL & Shell)

| Tool | Description |
|------|-------------|
| `ibmi_connect_ssh` | Connect via SSH |
| `ibmi_run_cl` | Execute a CL command (e.g., WRKACTJOB, DSPLIB) |
| `ibmi_run_shell` | Execute PASE/QShell command |

### ODBC/SQL (Database & Programs)

| Tool | Description |
|------|-------------|
| `ibmi_connect_odbc` | Connect to DB2/400 via ODBC |
| `ibmi_query` | Execute SQL (SELECT, INSERT, CALL, etc.) |
| `ibmi_call_program` | Call RPG/COBOL program via QCMDEXC |

### Spool File Management

| Tool | Description |
|------|-------------|
| `ibmi_list_spool_files` | List spool files for a user |
| `ibmi_read_spool_file` | Read content of a spool file |
| `ibmi_delete_spool_file` | Delete a spool file |

### Job Monitoring & Control

| Tool | Description |
|------|-------------|
| `ibmi_list_active_jobs` | List active jobs (filter by subsystem, user, type) |
| `ibmi_get_job_info` | Get detailed job info |
| `ibmi_get_job_log` | Retrieve job log messages |
| `ibmi_hold_job` | Hold (pause) a job |
| `ibmi_release_job` | Release a held job |
| `ibmi_end_job` | End a job (*CNTRLD or *IMMED) |

### Data Queue Operations

| Tool | Description |
|------|-------------|
| `ibmi_send_to_data_queue` | Send message to a data queue |
| `ibmi_receive_from_data_queue` | Receive/peek message from a data queue |
| `ibmi_clear_data_queue` | Clear all messages |

### IFS File Operations

| Tool | Description |
|------|-------------|
| `ibmi_ifs_list` | List files/directories in the IFS |
| `ibmi_ifs_read` | Read a text file |
| `ibmi_ifs_write` | Write text to a file |
| `ibmi_ifs_delete` | Delete a file |
| `ibmi_ifs_download` | Download file via SFTP |

### Message Queue Operations

| Tool | Description |
|------|-------------|
| `ibmi_list_messages` | List messages on a queue (QSYSOPR, etc.) |
| `ibmi_send_message` | Send message to a queue or user |
| `ibmi_reply_message` | Reply to an inquiry message |

### Object Management

| Tool | Description |
|------|-------------|
| `ibmi_list_objects` | List objects in a library |
| `ibmi_object_exists` | Check if object exists |
| `ibmi_get_object_description` | Get object metadata |
| `ibmi_list_libraries` | List libraries |

### Utility

| Tool | Description |
|------|-------------|
| `ibmi_status` | Check all connection statuses |

---

## 🔒 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:

```bash
python mock_as400_server.py --port 2323
```

Connect to it with:
```ini
IBMI_HOST=localhost
IBMI_PORT=2323
IBMI_USER=QSECOFR
IBMI_PASSWORD=QSECOFR
```

Available mock users:

| User | Password | Authority |
|------|----------|-----------|
| QSECOFR | QSECOFR | `*ALLOBJ` (admin) |
| DEVUSER | DEV123 | `*PGMR` (developer) |
| TESTUSER | TEST123 | `*USER` (basic) |

---

## 📁 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](LICENSE) for details.

---

## 🙏 Acknowledgments

Built with research from:
- [RFC 1205 — 5250 Telnet Interface](https://datatracker.ietf.org/doc/html/rfc1205)
- [IBM i Access ODBC](https://www.ibm.com/docs/en/i/7.5?topic=programming-i-access-odbc)
- [p5250 Python Library](https://pypi.org/project/p5250/)
- [JT400 (IBM Toolbox for Java)](https://jt400.sourceforge.net/)
- [QSYS2 SQL Services](https://www.ibm.com/docs/en/i/7.5?topic=services-sql)
- [MCP Specification](https://modelcontextprotocol.io/specification)