> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Mapepire

> Complete guide to installing and configuring Mapepire server on IBM i for MCP database connectivity

**Before you can use the IBM i MCP Server, you must install and configure Mapepire on your IBM i system.** Mapepire is the database connectivity layer that enables MCP tools and AI agents to communicate with Db2 for i.

<Warning>
  **Mapepire is Required**: The IBM i MCP Server cannot function without Mapepire. Install and configure Mapepire first before proceeding with server setup.
</Warning>

<Note>
  **Prerequisites**: You need SSH access to your IBM i system and appropriate administrative privileges to install software and configure network services.
</Note>

## What is Mapepire?

[Mapepire](https://mapepire-ibmi.github.io/) is a modern, high-performance database server for IBM i that provides SQL query execution capabilities over WebSocket connections. It acts as a gateway between modern application architectures (like MCP servers, AI agents, and REST APIs) and IBM i's Db2 for i database.

**Key Features**:

* Modern database server for IBM i
* SQL query execution over WebSocket connections
* Secure, encrypted connections to Db2 for i
* Optimized for AI agent workloads
* Supports modern authentication methods
* Low-latency responses for interactive applications

## Why Mapepire Enables AI and MCP Workloads

Traditional IBM i database access methods (ODBC, JDBC) don't align well with modern AI and MCP architectures that require:

* **Fast, lightweight connections**: AI agents make frequent, short-lived database queries
* **WebSocket support**: Enables real-time, bidirectional communication for streaming results
* **Modern JSON-based protocols**: Simplifies integration with TypeScript/JavaScript ecosystems
* **Low-latency responses**: Essential for interactive AI conversations and tool executions

Mapepire bridges this gap by providing a modern, WebSocket-based SQL query interface that's optimized for the request/response patterns of AI agents and MCP tools.

## Installation Methods

### Option 1: RPM Installation (Recommended)

The easiest way to install Mapepire is using the RPM package manager:

```bash theme={null}
# 1. Install Mapepire using yum
yum install mapepire-server

# 2. Install Service Commander (if not already installed)
yum install service-commander

# 3. Start Mapepire service
sc start mapepire
```

<Note>
  If you need help getting started with RPMs on IBM i, see the [IBM i Open Source RPM Guide](http://ibm.biz/ibmi-rpms).
</Note>

<Tip>
  **Full Documentation**: For comprehensive setup and configuration instructions, see the [Mapepire System Administrator Guide](https://mapepire-ibmi.github.io/guides/sysadmin/).
</Tip>

### Option 2: Manual Installation

If RPM installation isn't available, you can install manually:

1. **Create download directory:**
   ```bash theme={null}
   mkdir -p /opt/download
   ```

2. **Download the distribution:**
   ```bash theme={null}
   cd /opt/download
   wget -O mapepire-server-dist.zip \
     https://github.com/Mapepire-IBMi/mapepire-server/releases/latest/download/mapepire-server-dist.zip
   ```

3. **Extract and set permissions:**
   ```bash theme={null}
   mkdir -p /opt/mapepire
   cd /opt/mapepire
   jar xvf /opt/download/mapepire-server-dist.zip
   chown -R qsys .
   ```

## Starting Mapepire

### Service Commander (Recommended for RPM)

If you installed via RPM, use Service Commander for easy management:

```bash theme={null}
# Install Service Commander (if not already installed)
yum install service-commander

# Start the service
sc start mapepire

# Check if it's running
sc check mapepire

# Stop the service (when needed)
sc stop mapepire
```

### Manual Startup

**For RPM installation:**

```bash theme={null}
nohup /QOpenSys/pkgs/bin/mapepire &
```

**For manual installation:**

```bash theme={null}
nohup /opt/mapepire/bin/mapepire &
```

**For manual installation with Service Commander:**

```bash theme={null}
cd /opt/mapepire/lib/mapepire
sc start mapepire.yaml
```

## Configuration

### Port Configuration

Mapepire uses **port 8076** by default. This is the standard port and changing it is not recommended.

<Note>
  **Important**: You'll need port 8076 when configuring the `DB2i_PORT` variable in your `.env` file. Ensure your IBM i firewall allows inbound connections on this port.
</Note>

If you need to change the port:

```bash theme={null}
# Set environment variable
export PORT=8077

# Or edit Service Commander configuration
scedit mapepire
```

### TLS/SSL Configuration

Mapepire supports several TLS certificate options:

#### Option 1: Let's Encrypt (Recommended)

If you have Let's Encrypt certificates (e.g., from CertBot), Mapepire will automatically use them:

```bash theme={null}
# Certificates should be located at:
/etc/letsencrypt/live/<hostname>/
```

#### Option 2: Custom Certificate

Create a custom certificate store with these specifications:

| Setting           | Value                                    |
| ----------------- | ---------------------------------------- |
| File location     | `/QOpenSys/etc/mapepire/cert/server.jks` |
| Format            | JKS                                      |
| Store password    | `mapepire`                               |
| Key password      | `mapepire`                               |
| Certificate alias | `mapepire`                               |

**Example using DCM Tools:**

```bash theme={null}
dcmexport --password=changeit --dcm-store=system --format=pkcs12 mystore.p12

keytool -importkeystore \
  -srckeystore mystore.p12 \
  -srcstoretype pkcs12 \
  -srcstorepass changeit \
  -srcalias "mydcmalias" \
  -destkeystore /QOpenSys/etc/mapepire/cert/server.jks \
  -deststoretype JKS \
  -deststorepass mapepire \
  -destkeypass mapepire \
  -destalias mapepire
```

#### Option 3: Self-Signed Certificate

If no certificate is configured, Mapepire will automatically generate a self-signed certificate. This is suitable for development but not recommended for production.

### Security Configuration

#### Exit Points

Mapepire uses the same exit points as standard JDBC applications. For more information, see the [IBM Support page on JDBC exit points](https://www.ibm.com/support/pages/node/7073452).

<Warning>
  Due to Mapepire's architecture, all client connections appear to come from `127.0.0.1`. IP-based exit point rules will need to inspect the `CLIENT_WRKSTNNAME` client special register to get the actual client IP address.
</Warning>

#### Connection Rules

Configure user and IP-based access restrictions in:

```bash theme={null}
/QOpenSys/etc/mapepire/iprules.conf
```

**Rule format:**

* `allow <username>@<ip-address>`
* `deny <username>@<ip-address>`
* Use `*` as wildcard
* Last matching rule takes precedence
* Comments start with `#`

**Example - Disable Q* user profiles:*\*

```bash theme={null}
# Allow connections from all hosts
allow *@*

# Deny logins from users starting with Q
deny q*@*
```

**Example - Restrict to specific users and IP range:**

```bash theme={null}
# Deny by default
deny *@*

# Allow only specific users from 192.168.x.x
allow appusr1@192.168.*
allow appusr2@192.168.*
```

## Testing the Installation

### Verify Mapepire is Running

1. **Check the process:**
   ```bash theme={null}
   ps aux | grep mapepire
   ```

2. **Test connectivity:**
   ```bash theme={null}
   netstat -an | grep 8076
   ```

3. **Test with Service Commander:**
   ```bash theme={null}
   sc check mapepire
   ```

### Configure IBM i MCP Server

Once Mapepire is running, configure your IBM i MCP Server `.env` file:

```bash theme={null}
# IBM i connection settings
DB2i_HOST=your-ibmi-hostname
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true
```

<Note>
  Set `DB2i_IGNORE_UNAUTHORIZED=true` if using self-signed certificates. For production with proper certificates, set this to `false`.
</Note>

## Troubleshooting

### Common Issues

**Port already in use:**

```bash theme={null}
# Check what's using the port
netstat -an | grep 8076

# Kill existing process if needed
pkill mapepire
```

**Permission denied:**

```bash theme={null}
# Ensure proper ownership
chown -R qsys /opt/mapepire
```

**Certificate issues:**

```bash theme={null}
# Check certificate location and permissions
ls -la /QOpenSys/etc/mapepire/cert/
```

### Log Files

Check Mapepire logs for detailed error information:

```bash theme={null}
# Service Commander logs
sc logs mapepire

# Manual startup logs (if using nohup)
tail -f nohup.out
```

## Next Steps

After setting up Mapepire:

1. [Configure your IBM i MCP Server](/configuration)
2. [Test the connection](/quickstart#test-connection)
3. [Set up SQL tools](/sql-tools/building-tools)
4. [Build your first agent](/agents/building-agents)

## Additional Resources

* [Mapepire GitHub Repository](https://github.com/Mapepire-IBMi/mapepire-server)
* [Mapepire Documentation](https://mapepire-ibmi.github.io/)
* [IBM i Open Source Documentation](https://ibmi-oss-docs.readthedocs.io/)
* [DCM Tools for Certificate Management](https://github.com/ThePrez/DCM-tools/)