---
title: "Quick Start Guide"
description: "Get your IBM i MCP Server running in under 15 minutes with step-by-step setup instructions."
---
# 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.
<Note>
**Prerequisites**: You'll need access to an IBM i system with appropriate database authorities and Node.js 18+ installed on your development machine.
</Note>
## Step 1: Installation
Clone the repository and install dependencies:
```bash
git clone https://github.com/IBM/ibmi-mcp.git
cd ibmi-mcp
npm install
```
Build the project:
```bash
npm run build
```
<Tip>
Use `npm run rebuild` for a clean install if you encounter any issues.
</Tip>
## Step 2: Configuration
Create your environment configuration:
```bash
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
```
<Warning>
Replace the connection values with your actual IBM i system credentials. The user profile must have appropriate authorities for database operations.
</Warning>
<Note>
**Need to set up Mapepire?** If you don't have Mapepire running on your IBM i system yet, follow our [Setup Mapepire guide](/setup-mapepire) to install and configure the database connectivity layer.
</Note>
## Step 3: Start the Server
Launch the MCP server in HTTP mode:
```bash
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
```
<Success>
Your IBM i MCP Server is now running and ready to accept connections!
</Success>
## Step 4: Test with MCP Inspector
The easiest way to test your server is with the MCP Inspector tool.
Create the inspector configuration:
```bash
cp template_mcp.json mcp.json
```
Edit `mcp.json` with your connection details:
```json
{
"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:
```bash
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
<Accordion title="Example system_status output">
```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}"
}
]
}
```
</Accordion>
## Step 6: Build an Agent
Test with the included Python agent examples:
```bash
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
<CardGroup cols={2}>
<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>
<Card title="Production Deployment" icon="server" href="/deployment/production">
Deploy to production with authentication and monitoring
</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>
</AccordionGroup>
<Info>
**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](/configuration) or review the troubleshooting section above.
</Info>
