ibmi-mcp
This server gives AI agents terminal access to IBM i (AS/400) systems via TN5250 green-screen emulation, enabling full interactive control of the system.
Connect/Disconnect — Establish or terminate a TN5250 session to an IBM i system, with optional TLS encryption and SSH tunneling support when direct port access is unavailable
Read Screen — Capture the current 5250 screen content, including visible text, cursor position, input field metadata, and screen dimensions
Type Text — Send keystrokes/text input into the current input field at the cursor position
Send Function Keys — Trigger attention and function keys such as Enter, F1–F24, PageUp, PageDown, Tab, Backtab, Clear, Help, Print, and Attn
Position Cursor — Move the cursor to any specific row and column on the screen
Upload Files — Transfer files from the local machine to the IBM i Integrated File System (IFS) via SFTP
Download Files — Retrieve files from the IBM i IFS to the local system via SFTP
Auto-Signon — Automatically detect login screens and authenticate using configured credentials
Codepage Support — Handle EBCDIC codepage translation for proper character encoding
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ibmi-mcp Connect to my IBM i system and read the current screen."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ibmi-mcp
Give your AI Agent terminal access to your IBM i system via TN5250.
ibmi-mcp is an MCP server that lets AI Agents like Claude interact with IBM i the same way a human would through a 5250 green-screen terminal.
Installation
Install and register with Claude Code:
claude mcp add ibmi-5250 -- uvx ibmi-mcpThis requires the connection environment variables to be set in your shell profile. You can also pass them inline with -e flags:
claude mcp add ibmi-5250 \
-e IBMI_HOST=myhost.example.com \
-e IBMI_USER=myuser \
-e IBMI_PASSWORD=mypassword \
-- uvx ibmi-mcpRelated MCP server: ibmi-mcp-server
Configuration
Variable | Description | Required | Default |
| IBM i hostname or IP | Yes | — |
| TN5250 port | No | 23 |
| Enable TLS | No | false |
| Username for auto-signon | No | — |
| Password for auto-signon | No | — |
| Virtual device name | No | — |
| EBCDIC codepage | No | cp037 |
| Terminal type | No | IBM-3179-2 |
| Tunnel TN5250 through SSH | No | false |
| SSH port for file transfer and tunneling | No | 22 |
| Path to SSH private key | No | — |
| Path to known_hosts file | No | — |
When IBMI_USER and IBMI_PASSWORD are set, ibmi-mcp will automatically sign on when it detects a login screen after connecting.
Tools
Tool | Description |
| Connect to an IBM i system via TN5250 |
| Disconnect the active session |
| Read the current screen content and input fields |
| Type text into the current input field |
| Send a function/attention key (Enter, F1-F24, PageUp, PageDown, Tab, etc.) |
| Position the cursor at a specific row and column |
| Upload a file from the local system to the IBM i |
| Download a file from the IBM i to the local system |
Features
Auto-signon — Automatically detects sign-on screens and logs in with configured credentials
File transfer — Upload and download files to/from the IBM i IFS via SFTP
SSH tunneling — Tunnel TN5250 through SSH when port 23 is not directly reachable
Full key support — Enter, F1-F24, PageUp, PageDown, Tab, Backtab, Clear, Help, Print, Attn
Local editing — Backspace, Delete, Field Exit, Home, and End handled locally for responsive editing
Structured screen data — Returns screen text, cursor position, and input field metadata
Configurable codepage — Supports EBCDIC codepage translation (default: CP037)
License
BSD 2-Clause. See LICENSE for details.
About Whitehorn Ltd. Co.
ibmi-mcp is developed and maintained by Whitehorn Ltd. Co., a legacy system modernization firm. We specialize in IBM i, RPG, COBOL, and midrange platforms. We help our clients protect what they can't afford to break while building a path forward.
Learn more about how Whitehorn Ltd. Co. can help you modernize your IBM midrange systems at whitehorn.ltd.
Available Tools
8 toolsconnectA
Connect to an IBM i system via TN5250.
Args: host: IBM i hostname or IP. Defaults to IBMI_HOST env var. port: TN5250 port. Defaults to IBMI_PORT env var or 23. use_ssl: Enable TLS. Defaults to IBMI_SSL env var.
Returns the initial screen after connection.
Inputs: host, port, use_ssl.
disconnectA
Disconnect the active TN5250 session.
Inputs: no named parameters.
download_fileB
Download a file from the IBM i to the local system.
Args: remote_path: Path to the file on the IBM i (IFS path). local_path: Destination path on the local system.
Returns status with file details, or an error.
Inputs: remote_path (required), local_path (required).
read_screenA
Read the current 5250 screen content.
Returns structured data with:
screen: list of text rows (the visible display)
cursor: current cursor position {row, col} (1-based)
fields: list of input fields with position, length, value, and type
dimensions: screen size {rows, cols}
Inputs: no named parameters.
send_keyA
Send an attention/function key and wait for the host response.
Args: key: Key name. Valid values: Enter, F1-F24, PageUp, PageDown, Tab, Backtab, Clear, Help, Print, Attn.
Returns the updated screen after the host processes the key.
Inputs: key (required).
send_keysB
Type text into the current input field at the cursor position.
Args: text: The text to type.
Returns the updated screen state.
Inputs: text (required).
set_cursorA
Position the cursor at the specified location.
Args: row: Row number (1-based, top row is 1). col: Column number (1-based, leftmost column is 1).
Returns the updated screen state.
Inputs: row (required), col (required).
upload_fileB
Upload a file from the local system to the IBM i.
Args: local_path: Path to the file on the local system. remote_path: Destination path on the IBM i (IFS path).
Returns status with file details, or an error.
Inputs: local_path (required), remote_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation: session management (connect, disconnect), screen interaction (read_screen, send_key, send_keys, set_cursor), and file transfer (download_file, upload_file). There is no overlap, and agents can easily distinguish which tool to use.
All tool names follow a consistent verb_noun pattern with underscores (e.g., download_file, send_keys). There is no mixing of camelCase or other conventions, making the naming predictable and easy to remember.
With 8 tools, the server covers the essential operations for IBM i terminal emulation and file transfer without being overly large or minimal. The count is well-scoped for the server's purpose.
The tool set covers the core workflow: connect, interact with the screen, transfer files, and disconnect. A minor gap is the lack of a dedicated tool for waiting on screen conditions, but agents can achieve this by combining send_key and read_screen.
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact with IBM i AS/400 source members for source code management, compilation, and development workflows.7MIT
- 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
- AlicenseNot gradedqualityDmaintenanceBridges AI with IBM i systems for source code management, SQL queries, and schema inspection via MCP.1MIT
- AlicenseAqualityBmaintenanceAn MCP server that lets an AI agent use a real terminal the way a person does: type, press keys, click, read the screen, take a screenshot.1371 npm1MIT