Skip to main content
Glama

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

Related MCP server: ibmi-mcp-server

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.

Available Tools

8 tools
connectA

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

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers