Quick Start Guide

Get your IBM i MCP Server running in under 15 minutes with step-by-step setup instructions.

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.

---

Before You Begin

Complete these prerequisites before starting the installation:

1. Verify Node.js Installation

   Ensure Node.js 18 or higher is installed on your development machine:

   node --version
   # Should show v18.0.0 or higher
   

   Don’t have Node.js? Download from nodejs.org

2. Install Mapepire on IBM i

   Mapepire must be running on your IBM i system before proceeding.

   Not installed yet? Follow the Setup Mapepire guide (takes ~10 minutes)

   Already installed? Verify it’s running:

   # On IBM i
   sc check mapepire
   # Should show "running"
   

   Note the port: Default is 8076—you’ll need this for configuration.

3. Gather IBM i Credentials

   You’ll need:

   • IBM i hostname or IP address
   • User profile with database authorities
   • User password
   • Access to QSYS2 system services (verify with your system administrator)
4. Set Aside Time

   Plan for 15-20 minutes of uninterrupted setup time.

---

Step 1: Installation

Choose your installation method based on your needs:

NPM Package (Recommended)

Best for: Production use, quick setup, always-updated package

The official npm package provides instant installation without building from source.

# No installation needed - npx downloads and runs automatically
npx -y @ibm/ibmi-mcp-server@latest --help

Benefits:

• ✅ Always up-to-date with latest stable release
• ✅ No build step required
• ✅ Instant setup in seconds
• ✅ Automatic dependency management
• ✅ Perfect for CI/CD pipelines

The -y flag automatically accepts the npm package installation prompt. You can omit it if you want to confirm before installation.

Next: Skip to Step 2: Configuration

Build from Source

Best for: Development, customization, contributing, latest features

Repository Structure: The IBM i MCP Server follows a modular architecture:

• server/ - MCP server implementation (main package)
• tools/ - SQL tool YAML configurations
• agents/ - Agent implementations and examples
• deployment/ - Deployment configurations (Docker, Gateway, OpenShift)

Clone the repository and install dependencies:

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/server
npm install

Build the project:

npm run build

Use npm run rebuild for a clean install if you encounter any issues.

Benefits:

• ✅ Access to latest development features
• ✅ Ability to modify and customize code
• ✅ Contribute back to the project
• ✅ Debug and troubleshoot at source level

---

Step 2: Configuration

Create your environment configuration file:

NPM Package

Create a .env file in your current directory:

cat > .env << 'EOF'
# 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
EOF

Edit the file and replace the placeholder values with your actual IBM i credentials.

Build from Source

Copy the example configuration and edit it:

# From ibmi-mcp-server directory
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.

Mapepire is Required: Before proceeding, you must have Mapepire running on your IBM i system. Mapepire is a modern database server for IBM i that provides SQL query execution over WebSocket connections, optimized for AI agent workloads. If you haven’t installed it yet, follow our Setup Mapepire guide to install and configure it. Default port: 8076.

Explore All Configuration Options →

The Configuration guide covers authentication modes (JWT, OAuth, IBM i), HTTP/HTTPS settings, OpenTelemetry observability, and all environment variables with examples for development and production.

---

Step 3: Create Your First SQL Tool

SQL tools are YAML-based configurations that define SQL queries the MCP server can execute. Each tool specifies a data source, parameters, and the SQL statement to run.

Create Tools Directory

First, create a directory to store your tool configurations:

mkdir -p tools

Create a Simple Tool Configuration

Create a file named tools/quickstart.yaml with the following content:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true

tools:
  system_activity:
    source: ibmi-system
    description: "Current system activity information including active jobs and resource utilization"
    parameters: []
    statement: |
      SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())

toolsets:
  performance:
    tools:
      - system_activity

Understanding the YAML Structure

The YAML configuration has three main sections:

1. Sources

   Defines the IBM i data sources your tools will connect to. The environment variables (${DB2i_HOST}, etc.) are automatically replaced with values from your .env file.

   sources:
     ibmi-system:
       host: ${DB2i_HOST}
       user: ${DB2i_USER}
       password: ${DB2i_PASS}
   
2. Tools

   Defines the SQL operations available to AI agents. Each tool specifies:

   • source: Which data source to use
   • description: What the tool does (helps AI understand when to use it)
   • parameters: Input parameters (empty array [] means no parameters required)
   • statement: The SQL query to execute

   tools:
     system_activity:
       source: ibmi-system
       description: "Current system activity information including active jobs and resource utilization"
       parameters: []
       statement: |
         SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())
   
3. Toolsets

   Groups related tools together for easier management. You can load specific toolsets when starting the server using --toolsets performance.

   toolsets:
     performance:
       tools:
         - system_activity
   

Use Pre-Built Tools

Start with ready-made tools! Learn how to run the server with pre-built SQL tools for performance monitoring, security analysis, and system administration.

Build Custom Tools

Ready to build more tools? The SQL Tools documentation covers parameters, validation, multiple data sources, complex queries, and the full YAML configuration reference.

---

Step 4: Start the Server

Start the server in HTTP mode with your new SQL tool:

NPM Package (Recommended)

export MCP_SERVER_CONFIG=.env
npx -y @ibm/ibmi-mcp-server@latest --transport http --tools ./tools/quickstart.yaml

Session Modes:

• auto (default): Automatically detects client capabilities ← Start with this
• stateful: Maintains persistent sessions with connection state
• stateless: Each request is independent, no session state

Set via environment: MCP_SESSION_MODE=stateful npx -y @ibm/ibmi-mcp-server@latest --transport http

Build from Source

# From server/ directory
npm run start:http -- --tools ../tools/quickstart.yaml

Session Modes:

• auto (default): Automatically detects client capabilities ← Start with this
• stateful: Maintains persistent sessions with connection state
• stateless: Each request is independent, no session state

Set via environment: MCP_SESSION_MODE=stateful npm run start:http

Alternative: Stdio Transport - For MCP Inspector or CLI tools, use --transport stdio (NPM package) or npm run start:stdio (build from source). However, HTTP transport is recommended for most use cases.

Available CLI Options:

Option	Description	Example
--tools <path>	Override YAML tools path	--tools ./my-configs
--toolsets <list>	Load specific toolsets only	--toolsets performance,security
--transport <type>	Force transport type	--transport http
--help	Show help information	--help
--list-toolsets	List available toolsets	--list-toolsets

You should see output similar to:

✓ Server ready!
  Transport: http
  Host: 127.0.0.1:3010
  Endpoint: http://127.0.0.1:3010/mcp
  Tools loaded: 1

---

Step 5: Test with Sample MCP Client

Now that your server is running, test it with the example Python client from the GitHub repository to verify connectivity and tool execution.

Example Client Location: The sample client scripts are available in the client/ directory of the GitHub repository. Clone the repository or download the files to follow along.

Install uv (Python Package Manager)

If you don’t have uv installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Why uv? uv is a fast Python package manager that handles virtual environments and dependencies automatically. It’s the recommended way to run the client examples.

Run the MCP Client Script

In a new terminal window (keep the server running in the first terminal):

# Clone the repository if you haven't already
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/client

# Install dependencies and run the test client
uv run mcp_client.py

Already have the repo cloned? Just navigate to the client/ directory and run uv run mcp_client.py

You should see output like this:

================================================================================
AVAILABLE TOOLS
================================================================================
 1. system_activity
    └─ Get real-time IBM i system activity metrics

================================================================================
SYSTEM ACTIVITY RESULT
================================================================================

✓ Query executed successfully in 145ms
  SQL: SELECT * FROM QSYS2.SYSTEM_ACTIVITY_INFO

  Results (1 row(s)):
  ----------------------------------------------------------------------------
  SYSTEM_NAME                   : YOURSYSTEM
  CURRENT_TIMESTAMP             : 2024-12-10-15:30:45.123456
  CPU_UTILIZATION               : 15.2
  MEMORY_USED_MB                : 8192
  ACTIVE_JOBS                   : 542
  ----------------------------------------------------------------------------

What does this script do?

The mcp_client.py script:

1. Connects to your running MCP server at http://localhost:3010/mcp
2. Lists all available tools (SQL tools loaded from your YAML configs)
3. Executes the system_activity tool (a pre-built IBM i monitoring query)
4. Formats and displays the results

View Source: See the implementation at client/mcp_client.py to understand how to use the MCP client SDK.

---

Step 6: Run an AI Agent (Optional)

Now that you’ve verified the MCP server works, try the example AI agent from the GitHub repository that can answer natural language questions about your IBM i system.

Agent Script Location: The agent.py script is in the client/ directory of the GitHub repository. If you haven’t cloned the repo yet (from Step 5), you’ll need to do so first.

Configure API Key

The agent uses an LLM to understand your questions and call the appropriate MCP tools. You’ll need an API key:

OpenAI (Recommended)

Create a .env file in the client/ directory:

# From the client directory
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env

Get your API key: Visit OpenAI API Keys

Ollama (Local)

Install and run Ollama locally:

# Install Ollama (macOS)
brew install ollama

# Start Ollama and pull a model
ollama run qwen2.5

No API key needed—Ollama runs locally.

Run the Agent

From the client/ directory (where you ran the previous step), ask natural language questions about your IBM i system:

OpenAI

# If you skipped Step 5, clone the repo first:
# git clone https://github.com/IBM/ibmi-mcp-server.git
# cd ibmi-mcp-server/client

# Run the agent with OpenAI
uv run agent.py -p "What is my system performing?" --model-id "openai:gpt-4o"

# Or use the default prompt
uv run agent.py --model-id "openai:gpt-4o"

Ollama (Local)

# If you skipped Step 5, clone the repo first:
# git clone https://github.com/IBM/ibmi-mcp-server.git
# cd ibmi-mcp-server/client

# Run the agent with local Ollama
uv run agent.py -p "What is my system performing?" --model-id "ollama:qwen2.5"

# Or use the default prompt
uv run agent.py --model-id "ollama:qwen2.5"

Example interaction:

You: What is my system status?

Agent: Your IBM i system "YOURSYSTEM" is running normally with:
- CPU utilization at 15.2%
- 8GB of memory in use
- 542 active jobs
- System is responsive and healthy

The agent automatically:

1. Analyzes your natural language question
2. Selects the appropriate MCP tool(s) to call
3. Executes the tool(s) on your IBM i system
4. Synthesizes the results into a natural language response

View Source: See client/agent.py for the implementation details.

Build Production Agents

Ready for more? Explore our Agent Integrations documentation to build production-ready agents with Agno, Google ADK, or LangChain. Learn about FilteredMCPTools, specialized agent patterns, persistent memory, and multi-agent architectures.

---

🎉 Congratulations!

You’ve successfully set up the IBM i MCP Server! Here’s what you accomplished:

1. ✅ Server Installed

   Built and configured the MCP server with IBM i connection

2. ✅ Connection Verified

   Connected to Mapepire and your IBM i database

3. ✅ Tools Tested

   Listed and executed SQL tools via the MCP client

4. ✅ Agent Ready (Optional)

   Ran an AI agent that understands natural language queries

Your MCP server is now ready for:

• Connecting AI clients (Claude Desktop, VSCode, Cursor)
• Creating custom SQL tools for your specific use cases
• Building specialized agents for IBM i administration and monitoring

---

Next Steps

Client Integration

Connect the server to Claude Desktop, VSCode, Cursor, and 10+ other MCP clients

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

Troubleshooting

Connection Refused

• 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

Authentication Failed

• 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

Port Already in Use

Change the port in your .env file:

MCP_HTTP_PORT=3011

Then restart the server.

Tools Not Loading

• 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

Client Script Fails (mcp_client.py)

Connection refused or timeout:

• Ensure MCP server is running: check for “Server ready!” message
• Verify server is on port 3010 (or update script if using different port)
• Server must use HTTP transport (not stdio)

uv command not found:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart terminal or reload shell
source ~/.bashrc  # or ~/.zshrc

Python version error:

• Client requires Python 3.13+ (check pyproject.toml)
• Install Python 3.13: brew install python@3.13 (macOS)
• Or use uv python install 3.13

Dependencies fail to install:

# Clear uv cache and retry
cd client
rm -rf .venv
uv sync

Completion Time: This quickstart should take 20-30 minutes including the optional agent setup. Most time is spent waiting for installations and builds. If you encounter issues, check the configuration guide or review the troubleshooting section above.