Skip to main content

​
Quick Start Guide

Get your IBM i MCP Server up and running in under 15 minutes. This guide walks you through installation, configuration, and your first successful tool execution.
Prerequisites: You’ll need access to an IBM i system with appropriate database authorities and Node.js 18+ installed on your development machine.

​
Step 1: Installation

Clone the repository and install dependencies: 
git clone https://github.com/ajshedivy/ibmi-mcp-server.git
cd ibmi-mcp-server
npm install
Build the project: 
npm run build
Use npm run rebuild for a clean install if you encounter any issues.

​
Step 2: Configuration

Create your environment configuration: 
cp .env.example .env
Edit the .env file with your IBM i connection details: 
# IBM i DB2 for i Connection Settings
DB2i_HOST=your-ibmi-host
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

# Server Configuration
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
Replace the connection values with your actual IBM i system credentials. The user profile must have appropriate authorities for database operations.
Need to set up Mapepire? If you don’t have Mapepire running on your IBM i system yet, follow our Setup Mapepire guide to install and configure the database connectivity layer.

​
Step 3: Start the Server

Launch the MCP server in HTTP mode: 
npm run start:http
You should see output similar to: 
✓ Server ready!
  Transport: http
  Host: 127.0.0.1:3010
  Endpoint: http://127.0.0.1:3010/mcp

​
Step 4: Test with MCP Inspector

The easiest way to test your server is with the MCP Inspector tool. Create the inspector configuration: 
cp template_mcp.json mcp.json
Edit mcp.json with your connection details: 
{
  "mcpServers": {
    "default-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "TOOLS_YAML_PATH": "prebuiltconfigs",
        "DB2i_HOST": "your-ibmi-host",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
Start the MCP Inspector: 
npm run mcp-inspector
Open the URL shown in your browser (typically http://localhost:6274).

​
Step 5: Execute Your First Tool

In the MCP Inspector:
  1. View Available Tools: You should see several IBM i tools like system_status, active_job_info, etc.
  2. Execute a Tool: Click on system_status and then “Execute Tool”
  3. View Results: You should see IBM i system performance data returned as JSON 
{
  "content": [
    {
      "type": "text",
      "text": "System Status Results: {\n  \"SYSTEM_NAME\": \"YOURSYSTEM\",\n  \"CURRENT_TIMESTAMP\": \"2024-01-15-10.30.45.123456\",\n  \"CPU_UTILIZATION\": 15.2,\n  \"MEMORY_USED_MB\": 8192,\n  \"DISK_UTILIZATION\": 45.8\n}"
    }
  ]
}

​
Step 6: Build an Agent

Test with the included Python agent examples: 
cd agents

# Install dependencies and run an agent
uv run agent.py -p "What is my system status?"
The agent will connect to your running server and execute the system_status tool, returning a natural language summary of your IBM i system performance.

​
Next Steps

SQL Tools

Learn how to create custom SQL operations using YAML configurations

Configuration

Explore all configuration options and environment variables

Agent Development

Build sophisticated AI agents that understand IBM i concepts

Production Deployment

Deploy to production with authentication and monitoring

​
Troubleshooting

  • Verify your IBM i host is reachable: ping your-ibmi-host
  • Check that the Mapepire daemon is running on port 8076
  • Ensure your user profile has database authorities
  • Verify your IBM i username and password are correct
  • Check that your user profile is not disabled or expired
  • Ensure you have appropriate authorities for QSYS2 services
Change the port in your .env file:
MCP_HTTP_PORT=3011
Then restart the server.
  • Check that prebuiltconfigs/ directory exists
  • Verify your YAML tool configurations are valid
  • Use --list-toolsets to see available tools:
npm run start:http -- --list-toolsets
Completion Time: This quickstart should take 10-15 minutes depending on your IBM i system response times. If you encounter issues, check the configuration guide or review the troubleshooting section above.