IBM i MCP Server

--- title: "Quick Start Guide" description: "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: <Steps> <Step title="Verify Node.js Installation"> Ensure Node.js 18 or higher is installed on your development machine: ```bash node --version # Should show v18.0.0 or higher ``` **Don't have Node.js?** Download from [nodejs.org](https://nodejs.org/) </Step> <Step title="Install Mapepire on IBM i"> Mapepire must be running on your IBM i system before proceeding. **Not installed yet?** Follow the [Setup Mapepire guide](/setup-mapepire) (takes ~10 minutes) **Already installed?** Verify it's running: ```bash # On IBM i sc check mapepire # Should show "running" ``` **Note the port**: Default is 8076—you'll need this for configuration. </Step> <Step title="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) </Step> <Step title="Set Aside Time"> Plan for 15-20 minutes of uninterrupted setup time. </Step> </Steps> <Success> ✓ **Ready to proceed?** All prerequisites met? Continue to installation. </Success> --- ## Step 1: Installation Choose your installation method based on your needs: <Tabs> <Tab title="NPM Package (Recommended)"> **Best for:** Production use, quick setup, always-updated package The official npm package provides instant installation without building from source. ```bash # 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 <Note> The `-y` flag automatically accepts the npm package installation prompt. You can omit it if you want to confirm before installation. </Note> <Success> ✓ **Verify the package works:** ```bash npx -y @ibm/ibmi-mcp-server@latest --help ``` You should see the help output with available options. </Success> **Next:** Skip to [Step 2: Configuration](#step-2-configuration) </Tab> <Tab title="Build from Source"> **Best for:** Development, customization, contributing, latest features <Note> **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) </Note> Clone the repository and install dependencies: ```bash git clone https://github.com/IBM/ibmi-mcp-server.git cd ibmi-mcp-server/server npm install ``` Build the project: ```bash npm run build ``` <Tip> Use `npm run rebuild` for a clean install if you encounter any issues. </Tip> <Success> ✓ **Verify the build succeeded:** - No error messages in the output - `dist/` directory was created - `dist/index.js` exists **Build failed?** Check that Node.js 18+ is installed and all dependencies downloaded successfully. </Success> **Benefits:** - ✅ Access to latest development features - ✅ Ability to modify and customize code - ✅ Contribute back to the project - ✅ Debug and troubleshoot at source level </Tab> </Tabs> --- ## Step 2: Configuration Create your environment configuration file: <Tabs> <Tab title="NPM Package"> Create a `.env` file in your current directory: ```bash 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. </Tab> <Tab title="Build from Source"> Copy the example configuration and edit it: ```bash # From ibmi-mcp-server directory cp .env.example .env ``` Edit the `.env` file with your IBM i connection details: ```bash # 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 ``` </Tab> </Tabs> <Warning> Replace the connection values with your actual IBM i system credentials. The user profile must have appropriate authorities for database operations. </Warning> <Warning> **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](/setup-mapepire) to install and configure it. Default port: **8076**. </Warning> <Success> ✓ **Verify your configuration:** - `.env` file exists in the root directory - `DB2i_HOST` is set to your IBM i hostname (not `127.0.0.1` if running in Docker) - `DB2i_USER` and `DB2i_PASS` are valid IBM i credentials - `DB2i_PORT` matches your Mapepire port (default: 8076) **Having connection issues?** See the [troubleshooting section](#troubleshooting) below. </Success> <Card title="Explore All Configuration Options →" icon="gear" href="/configuration"> 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. </Card> --- ## 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: ```bash mkdir -p tools ``` ### Create a Simple Tool Configuration Create a file named `tools/quickstart.yaml` with the following content: ```yaml 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: <Steps> <Step title="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. ```yaml sources: ibmi-system: host: ${DB2i_HOST} user: ${DB2i_USER} password: ${DB2i_PASS} ``` </Step> <Step title="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 ```yaml 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()) ``` </Step> <Step title="Toolsets"> Groups related tools together for easier management. You can load specific toolsets when starting the server using `--toolsets performance`. ```yaml toolsets: performance: tools: - system_activity ``` </Step> </Steps> <Success> ✓ **Verify your tool configuration:** - `tools/quickstart.yaml` file exists - YAML syntax is valid (no tabs, proper indentation with spaces) - Environment variables are wrapped in `${}` syntax - SQL statement uses the pipe `|` character for multi-line strings </Success> <CardGroup cols={2}> <Card title="Use Pre-Built Tools" icon="box" href="/sql-tools/using-default-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. </Card> <Card title="Build Custom Tools" icon="hammer" href="/sql-tools/overview"> **Ready to build more tools?** The SQL Tools documentation covers parameters, validation, multiple data sources, complex queries, and the full YAML configuration reference. </Card> </CardGroup> --- ## Step 4: Start the Server Start the server in HTTP mode with your new SQL tool: <Tabs> <Tab title="NPM Package (Recommended)"> ```bash 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` </Tab> <Tab title="Build from Source"> ```bash # 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` </Tab> </Tabs> <Note> **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. </Note> **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 ``` <Success> ✓ **Verify the server started successfully:** - See "Server ready!" message - HTTP endpoint is displayed (or "Stdio ready" for stdio mode) - Number of tools loaded shown (should be > 0) - No error messages about Mapepire connection - Server process remains running (doesn't exit immediately) **Server not starting?** Check: 1. Mapepire is running on IBM i: `sc check mapepire` 2. Firewall allows connection to port 8076 3. IBM i credentials are correct in `.env` 4. No other process is using port 3010 (HTTP mode) </Success> --- ## Step 5: Test with Sample MCP Client Now that your server is running, test it with the example Python client from the [GitHub repository](https://github.com/IBM/ibmi-mcp-server/tree/main/client) to verify connectivity and tool execution. <Note> **Example Client Location**: The sample client scripts are available in the [`client/`](https://github.com/IBM/ibmi-mcp-server/tree/main/client) directory of the GitHub repository. Clone the repository or download the files to follow along. </Note> ### Install uv (Python Package Manager) If you don't have `uv` installed: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` <Note> **Why uv?** [uv](https://github.com/astral-sh/uv) is a fast Python package manager that handles virtual environments and dependencies automatically. It's the recommended way to run the client examples. </Note> ### Run the MCP Client Script In a **new terminal window** (keep the server running in the first terminal): ```bash # 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 ``` <Tip> **Already have the repo cloned?** Just navigate to the `client/` directory and run `uv run mcp_client.py` </Tip> 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 ---------------------------------------------------------------------------- ``` <Success> ✓ **Verify your connection works:** - List of available tools displayed - `system_activity` tool executed successfully - Real data from your IBM i system returned - No connection errors or timeouts **Not seeing data?** Check: 1. MCP server is still running (check first terminal) 2. Server started on port 3010 (matches script's `localhost:3010`) 3. No firewall blocking local connections 4. Server logs show the incoming request </Success> <Accordion title="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`](https://github.com/IBM/ibmi-mcp-server/blob/main/client/mcp_client.py) to understand how to use the MCP client SDK. </Accordion> --- ## 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](https://github.com/IBM/ibmi-mcp-server/tree/main/client) that can answer natural language questions about your IBM i system. <Note> **Agent Script Location**: The `agent.py` script is in the [`client/`](https://github.com/IBM/ibmi-mcp-server/tree/main/client) directory of the GitHub repository. If you haven't cloned the repo yet (from Step 5), you'll need to do so first. </Note> ### Configure API Key The agent uses an LLM to understand your questions and call the appropriate MCP tools. You'll need an API key: <Tabs> <Tab title="OpenAI (Recommended)"> Create a `.env` file in the `client/` directory: ```bash # From the client directory echo "OPENAI_API_KEY=your-openai-api-key-here" > .env ``` **Get your API key**: Visit [OpenAI API Keys](https://platform.openai.com/api-keys) </Tab> <Tab title="Ollama (Local)"> Install and run Ollama locally: ```bash # Install Ollama (macOS) brew install ollama # Start Ollama and pull a model ollama run qwen2.5 ``` No API key needed—Ollama runs locally. </Tab> </Tabs> ### Run the Agent From the `client/` directory (where you ran the previous step), ask natural language questions about your IBM i system: <Tabs> <Tab title="OpenAI"> ```bash # 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" ``` </Tab> <Tab title="Ollama (Local)"> ```bash # 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" ``` </Tab> </Tabs> **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 ``` <Tip> 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`](https://github.com/IBM/ibmi-mcp-server/blob/main/client/agent.py) for the implementation details. </Tip> <Card title="Build Production Agents" icon="rocket" href="/agents/overview"> **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. </Card> --- ## 🎉 Congratulations! You've successfully set up the IBM i MCP Server! Here's what you accomplished: <Steps> <Step title="✅ Server Installed"> Built and configured the MCP server with IBM i connection </Step> <Step title="✅ Connection Verified"> Connected to Mapepire and your IBM i database </Step> <Step title="✅ Tools Tested"> Listed and executed SQL tools via the MCP client </Step> <Step title="✅ Agent Ready (Optional)"> Ran an AI agent that understands natural language queries </Step> </Steps> 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 <CardGroup cols={2}> <Card title="Client Integration" icon="plug" href="/clients/overview"> Connect the server to Claude Desktop, VSCode, Cursor, and 10+ other MCP clients </Card> <Card title="SQL Tools" icon="database" href="/sql-tools/overview"> Learn how to create custom SQL operations using YAML configurations </Card> <Card title="Configuration" icon="gear" href="/configuration"> Explore all configuration options and environment variables </Card> <Card title="Agent Development" icon="robot" href="/agents/building-agents"> Build sophisticated AI agents that understand IBM i concepts </Card> </CardGroup> ## Troubleshooting <AccordionGroup> <Accordion title="Connection Refused" icon=""> - 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 </Accordion> <Accordion title="Authentication Failed" icon=""> - 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 </Accordion> <Accordion title="Port Already in Use" icon=""> Change the port in your `.env` file: ```bash MCP_HTTP_PORT=3011 ``` Then restart the server. </Accordion> <Accordion title="Tools Not Loading" icon=""> - Check that `prebuiltconfigs/` directory exists - Verify your YAML tool configurations are valid - Use `--list-toolsets` to see available tools: ```bash npm run start:http -- --list-toolsets ``` </Accordion> <Accordion title="Client Script Fails (mcp_client.py)" icon=""> **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:** ```bash # 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:** ```bash # Clear uv cache and retry cd client rm -rf .venv uv sync ``` </Accordion> </AccordionGroup> <Info> **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](/configuration) or review the troubleshooting section above. </Info>