ibmi-mcp 1.1.0

MCP server providing 5250 terminal access to IBM i systems

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

This 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-mcp

Configuration

Variable	Description	Required	Default
IBMI_HOST	IBM i hostname or IP	Yes	—
IBMI_PORT	TN5250 port	No	23
IBMI_SSL	Enable TLS	No	false
IBMI_USER	Username for auto-signon	No	—
IBMI_PASSWORD	Password for auto-signon	No	—
IBMI_DEVICE_NAME	Virtual device name	No	—
IBMI_CODEPAGE	EBCDIC codepage	No	cp037
IBMI_TERMINAL_TYPE	Terminal type	No	IBM-3179-2
IBMI_SSH_TUNNEL	Tunnel TN5250 through SSH	No	false
IBMI_SSH_PORT	SSH port for file transfer and tunneling	No	22
IBMI_SSH_KEY_FILE	Path to SSH private key	No	—
IBMI_SSH_KNOWN_HOSTS	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	Connect to an IBM i system via TN5250
disconnect	Disconnect the active session
read_screen	Read the current screen content and input fields
send_keys	Type text into the current input field
send_key	Send a function/attention key (Enter, F1-F24, PageUp, PageDown, Tab, etc.)
set_cursor	Position the cursor at a specific row and column
upload_file	Upload a file from the local system to the IBM i
download_file	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.