Standalone MCP Host (@bdkinc/ibmi-mcp)

This package contains the standalone Model Context Protocol (MCP) host used for external harnesses, AI agents, and IDE validation.

Prerequisites

To connect using the MCP host, ensure the following requirements are met on both the client PC and the IBM i host:

1. IBM i Access ODBC Driver The local machine running the MCP server must have the ODBC driver installed.

   • ODBC Installation Instructions

2. SSH Service The SSH server must be running on the IBM i host.

   • Start the service using: STRTCPSVR *SSHD

3. SSH-Compatible Credentials Connections require credentials with an enabled shell. Profiles without passwords or user profiles like QSECOFR that are typically restricted from SSH access shouldn't be used directly unless appropriately configured. The user must also conform to PASE password constraints.

   • Configuring IBM i SSH, SFTP, and SCP clients to use public key authentication%20LEVEL(*SYS))

4. Required Packages The IBM i host must have itoolkit-utils installed for running tools securely via SSH. (e.g., yum install itoolkit-utils)

Usage

You can run the server directly via npx without needing to clone the repository:

npx -y @bdkinc/ibmi-mcp --transport stdio

During prerelease testing, use the next dist-tag explicitly:

npx -y @bdkinc/ibmi-mcp@next --transport stdio

When running via npx, provide your IBM i connection configuration using environment variables:

MCP_HOST=my-ibmi MCP_USERNAME=myuser MCP_PASSWORD_SECRET=mysecret MCP_CURRENT_SCHEMA=MYLIB npx -y @bdkinc/ibmi-mcp --transport stdio

The CLI also supports a few basic flags that are useful when validating external installs:

npx -y @bdkinc/ibmi-mcp --help
npx -y @bdkinc/ibmi-mcp --version

Application Integration Examples

VS Code (e.g., Roo Code / GitHub Copilot)

For VS Code extensions that support MCP clients, you can configure the server using a mcp.json settings file:

{
  "mcpServers": {
    "ibmi-ai": {
       "command": "npx",
       "args": ["-y", "@bdkinc/ibmi-mcp@next", "--transport", "stdio"],
       "env": {
         "MCP_PROFILE_LABEL": "Local IBM i",
         "MCP_HOST": "your-ibmi-host",
        "MCP_USERNAME": "your-user",
        "MCP_PASSWORD_SECRET": "YOUR-PASSWORD-HERE",
        "MCP_CURRENT_SCHEMA": "MYLIB", // Optional: initialize CURRENT SCHEMA for each pooled ODBC session
        "MCP_ALLOWED_COMMAND_NAMES": "CRTUSRPRF,CHGUSRPRF,ENDJOB,HLDJOB,RLSJOB,DLTSPLF,HLDSPLF,CHGSPLF,STRTCPSVR,ENDTCPSVR" // Optional: gate allowed commands, e.g. "CRTUSRPRF,CHGUSRPRF,ENDJOB"
      }
    }
  }
}

(Note: Depending on your extension features, you can prompt for the password securely using input variables if supported, such as "${input:ibmi-password}").

When moving from prerelease testing to the normal published package, remove @next from the package name in the args array.

Claude Desktop

To use the IBM i tools from the Claude Desktop app, edit your Claude config file (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ibmi-ai": {
      "command": "npx",
      "args": ["-y", "@bdkinc/ibmi-mcp@next", "--transport", "stdio"],
      "env": {
        "MCP_HOST": "your-ibmi-host",
        "MCP_USERNAME": "your-user",
        "MCP_PASSWORD_SECRET": "YOUR-PASSWORD-HERE",
        "MCP_CURRENT_SCHEMA": "MYLIB", // Optional: initialize CURRENT SCHEMA for each pooled ODBC session
        "MCP_ALLOWED_COMMAND_NAMES": "CRTUSRPRF,CHGUSRPRF,ENDJOB,HLDJOB,RLSJOB,DLTSPLF,HLDSPLF,CHGSPLF,STRTCPSVR,ENDTCPSVR" // Optional: gate allowed commands
      }
    }
  }
}

Local Development & Environment Configuration

If you are developing locally inside the source repository, you can set the environment variables via .env files in this directory (e.g. .env, .env.example, .env.local.example).

Typical variables include:

• MCP_TRANSPORT
• MCP_PROFILE
• MCP_HTTP_*
• MCP_HOST, MCP_PORT, MCP_DATABASE, MCP_CURRENT_SCHEMA, MCP_USERNAME, MCP_PASSWORD_SECRET, MCP_LIBRARY_LIST
• standalone runtime MCP_* tuning for sessions and command execution

Common scripts for local monorepo development:

• npm run dev --workspace @bdkinc/ibmi-mcp
• npm run build --workspace @bdkinc/ibmi-mcp
• npm run start --workspace @bdkinc/ibmi-mcp
• npm run test:live-smoke --workspace @bdkinc/ibmi-mcp

Live smoke test requirements:

• Export the same IBM i connection variables used by the standalone host, for example MCP_HOST, MCP_USERNAME, and MCP_PASSWORD_SECRET.
• If you want the smoke test to exercise approval-backed command execution, also provide MCP_COMMAND_EXECUTION_ENABLED=true and MCP_FREEFORM_COMMAND_EXECUTION_ENABLED=true.
• The script sets RUN_IBM_I_LIVE_SMOKE=1 automatically and runs tests/live-smoke.test.ts in a subprocess so it can load the standalone itoolkit runtime correctly under Node.

Behavior Notes

• This standalone host exposes observe, recommend, and act tools.
• Command-backed tools execute as the configured IBM i profile.
• The standalone itoolkit path is fixed by the host implementation; there is no standalone MCP_ITOOLKIT_TRANSPORT override.
• plan_run_ibmi_command, approve_ibmi_command_request, and run_ibmi_command use local in-memory approval state for the standalone process.
• Restarting the standalone process clears those local approval records.
• MCP_ALLOWED_COMMAND_NAMES is optional. If provided, it strictly gates which CL commands can be executed via run_ibmi_command. If you wish to allow everything without a whitelist, set MCP_FREEFORM_COMMAND_EXECUTION_ENABLED=true.