ibmi-mcp-server
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"ibmi-mcp": {
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
},
"type": "streamableHttp",
"url": "http://localhost:3010/mcp"
}
}
}
服务介绍
ibmi-mcp-server
MCP server for IBM i
** Documentation | Docs are under active development**

- ibmi-mcp-server
- Quickstart
- Installing in MCP Clients
- IBM i Agents
- Configuration
- IBM i HTTP Authentication (Beta)
- SQL Tool Configuration
- Running the Server (Development)
- MCP Inspector
- Docker & Podman Deployment
- Architecture Overview
- License
Quickstart
1. Installation
Clone the repository and install dependencies:
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/
npm install
2. Build the Project
npm run build
# Or use 'npm run rebuild' for a clean install
3. Create Server .env File
cp .env.example .env
Fill out the Db2 for i connection details in the .env file:
# IBM i DB2 for i Connection Settings
# Required for YAML SQL tools to connect to IBM i systems
DB2i_HOST=
DB2i_USER=
DB2i_PASS=
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true
See more on configuration options in the Configuration section.
4. Running the Server
-
Via Stdio (Default):
npm run start:stdio -
Via Streamable HTTP:
npm run start:httpBy Default, the server registers SQL tools stored in the
prebuiltconfigsdirectory. This path is set in the.envfile (TOOLS_YAML_PATH). You can override the SQL tools path using the CLI:- CLI Option:
--tools <path>npm run start:http -- --tools <path> - Transport Options:
--transport <type>npm run start:http -- --transport http # or stdio
- CLI Option:
5. Run Example Agent
Make sure that the server is running in http mode:
npm run start:http
In another terminal, navigate to the tests/agents directory and follow the setup instructions in the README.
Run the example Agent:
cd tests/agents
export OPENAI_API_KEY=your_open_ai_key
uv run agent.py -p "What is my system status?"
Run the Example Scripts:
cd tests/agents
# See a list of configured tools:
uv run test_tool_annotations.py
# see a list of server resources:
uv run test_toolset_resources.py
Note:
test_tool_annotations.pyandrun test_toolset_resources.pyDO NOT require and OpenAI API Key
6. Running Tests
This template uses Vitest for testing, with a strong emphasis on integration testing to ensure all components work together correctly.
- Run all tests once:
npm test - Run tests in watch mode:
npm run test:watch - Run tests and generate a coverage report:
npm run test:coverage
Installing in MCP Clients
This server can be integrated into any MCP-compatible client using either local (stdio) or remote (HTTP) connections.
Prerequisites: Local Installation
For local development, install the server globally using npm link:
# From the ibmi-mcp-server directory
npm install
npm run build
npm link
This makes the ibmi-mcp-server command available globally on your machine. After linking, you can use npx ibmi-mcp-server in any client configuration.
Note:
TOOLS_YAML_PATHmust be an absolute path to your tools configuration directory (e.g.,/full/path/to/prebuiltconfigs).
Remote Server Setup
For HTTP remote connections, you need to:
-
Start the server with IBM i authentication enabled:
# Ensure your .env has these settings: MCP_AUTH_MODE=ibmi IBMI_HTTP_AUTH_ENABLED=true IBMI_AUTH_ALLOW_HTTP=true # For development only! npm run start:http -
Obtain an access token:
# Use the token script to authenticate node get-access-token.js --verbose # Or set it directly in your environment export IBMI_MCP_ACCESS_TOKEN="your-token-here"See IBM i HTTP Authentication for detailed authentication setup.
-
Configure your client with the server URL and Bearer token (examples below).
** Production Note:** Replace
http://localhost:3010with your production endpoint URL and ensure HTTPS is enabled (IBMI_AUTH_ALLOW_HTTP=false).
Client Configurations
Claude Code supports both local (stdio) and remote (HTTP) MCP server connections. You can configure servers using the CLI or by editing .mcp.json directly.
Option 1: Local Stdio Server (Recommended)
Using CLI:
# Add local stdio server
claude mcp add ibmi-mcp \
--env DB2i_HOST=your-ibmi-host.com \
--env DB2i_USER=your-username \
--env DB2i_PASS=your-password \
--env DB2i_PORT=8076 \
--env MCP_TRANSPORT_TYPE=stdio \
-- npx ibmi-mcp-server --tools /absolute/path/to/prebuiltconfigs
Using .mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio",
"NODE_OPTIONS": "--no-deprecation"
}
}
}
}
Option 2: Remote HTTP Server
Using CLI:
# Add remote HTTP server with authentication
claude mcp add --transport http ibmi-mcp http://localhost:3010/mcp \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"
Using .mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Environment Variable Expansion
Claude Code supports environment variable expansion in .mcp.json files, allowing you to keep credentials secure:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "${IBMI_TOOLS_PATH}"],
"env": {
"DB2i_HOST": "${DB2i_HOST}",
"DB2i_USER": "${DB2i_USER}",
"DB2i_PASS": "${DB2i_PASS}",
"DB2i_PORT": "${DB2i_PORT:-8076}",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Supported syntax:
${VAR}- Expands to the value of environment variableVAR${VAR:-default}- Expands toVARif set, otherwise usesdefault
Managing Servers
# List configured servers
claude mcp list
# Get server details
claude mcp get ibmi-mcp
# Remove a server
claude mcp remove ibmi-mcp
# Check server status in Claude Code
/mcp
Local (Stdio)
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
VSCode supports MCP servers through Copilot Chat. You can configure servers at the user or workspace level using configuration files or the CLI.
Prerequisites: Ensure GitHub Copilot is installed and enabled.
Configuration File Locations
- Workspace:
.vscode/mcp.json(shared with team via version control) - User:
mcp.jsonin your user profile directory- macOS/Linux:
~/.config/Code/User/globalStorage/modelcontextprotocol.mcp/mcp.json - Windows:
%APPDATA%\Code\User\globalStorage\modelcontextprotocol.mcp\mcp.json
- macOS/Linux:
Option 1: Local Stdio Server
Using CLI:
# Add local stdio server
code --add-mcp '{
"name": "ibmiMcp",
"type": "stdio",
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}'
Using mcp.json:
{
"servers": {
"ibmiMcp": {
"type": "stdio",
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Option 2: Remote HTTP Server
Using CLI:
# Add remote HTTP server
code --add-mcp '{
"name": "ibmiMcp",
"type": "http",
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}'
Using mcp.json:
{
"servers": {
"ibmiMcp": {
"type": "http",
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Secure Credentials with Input Variables
VSCode supports input variables to avoid hardcoding sensitive credentials:
{
"inputs": [
{
"id": "db2iHost",
"type": "promptString",
"description": "IBM i DB2 host address"
},
{
"id": "db2iUser",
"type": "promptString",
"description": "IBM i username"
},
{
"id": "db2iPass",
"type": "promptString",
"description": "IBM i password",
"password": true
}
],
"servers": {
"ibmiMcp": {
"type": "stdio",
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "${input:db2iHost}",
"DB2i_USER": "${input:db2iUser}",
"DB2i_PASS": "${input:db2iPass}",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
VSCode will prompt for these values when the server starts, keeping credentials secure.
Managing Servers
- View servers: Check the Copilot Chat view in the Activity Bar
- Restart server: Use Command Palette (
Cmd/Ctrl+Shift+P) "MCP: Restart Server" - Disable server: Remove from
mcp.jsonor disable in settings
Local (Stdio)
Add to Cursor settings or .cursor/mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Local (Stdio)
Add to Windsurf configuration:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Local (Stdio)
Configure in Roo Code settings:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Local (Stdio)
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio",
"NODE_OPTIONS": "--no-deprecation"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Local (Stdio)
Add local MCP servers using "type": "local" within the MCP object. Multiple MCP servers can be added. The key string for each server can be any arbitrary name.
opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ibmi-mcp": {
"type": "local",
"enabled": true,
"command": ["npx", "ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"environment": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
},
"enabled": true
}
}
}
You can also disable a server by setting enabled to false. This is useful if you want to temporarily disable a server without removing it from your config.
Remote (HTTP)
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ibmi-mcp": {
"type": "remote",
"enabled": true,
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
See Gemini CLI Configuration for details.
- Open the Gemini CLI settings file. The location is
~/.gemini/settings.json(where~is your home directory). - Add the following to the
mcpServersobject in yoursettings.jsonfile:
Local (Stdio)
Configure in Gemini CLI settings:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Remote (HTTP)
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Cline supports MCP servers through both the marketplace and manual configuration.
Prerequisites: Ensure Cline is installed in VSCode.
Option 1: Manual Configuration
For Local (Stdio) Server:
- Open Cline
- Click the hamburger menu icon () MCP Servers
- Choose Local Servers tab
- Click Edit Configuration
- Add the configuration:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
For Remote (HTTP) Server:
- Open Cline
- Click the hamburger menu icon () MCP Servers
- Choose Remote Servers tab
- Click Edit Configuration
- Add the configuration:
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "streamableHttp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Remote (HTTP) with Agno
import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MCPTools, StreamableHTTPClientParams
# Get access token from environment
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")
url = "http://localhost:3010/mcp"
server_params = StreamableHTTPClientParams(
url=url,
headers={"Authorization": f"Bearer {token}"}
)
async def main():
async with MCPTools(
url=url,
server_params=server_params,
transport="streamable-http"
) as tools:
# List available tools
result = await tools.session.list_tools()
print(f"Available tools: {[t.name for t in result.tools]}")
# Create agent
agent = Agent(
model="openai:gpt-4o", # or your preferred model
tools=[tools],
name="ibmi-agent",
show_tool_calls=True
)
# Run query
await agent.aprint_response("What is the system status?")
if __name__ == "__main__":
asyncio.run(main())
Remote (HTTP) with Official MCP SDK
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")
headers = {"Authorization": f"Bearer {token}"}
async with streamablehttp_client(
"http://localhost:3010/mcp",
headers=headers
) as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
# List tools
tools = await session.list_tools()
print(f"Tools: {[t.name for t in tools.tools]}")
# Execute a tool
result = await session.call_tool("system_status", {})
print(result)
if __name__ == "__main__":
asyncio.run(main())
Troubleshooting
Connection Issues:
- Verify
npm linkwas successful:which ibmi-mcp-server - Check that
TOOLS_YAML_PATHis an absolute path - Ensure IBM i credentials are correct
Authentication Failures (Remote):
- Confirm server is running with
IBMI_HTTP_AUTH_ENABLED=true - Verify token is valid:
echo $IBMI_MCP_ACCESS_TOKEN - Check server logs for authentication errors
Tool Loading Errors:
- Validate YAML configuration:
npm run validate -- --config prebuiltconfigs - Check file permissions on tools directory
- Review server startup logs for parsing errors
IBM i Agents
IBM i Agents are specialized components designed to interact with the IBM i system, providing capabilities such as monitoring, management, and automation.
Key Features
- Integration with IBM i: Seamless integration with IBM i system APIs and tools.
- Modular Architecture: Easily extendable and customizable to fit specific use cases.
- Real-time Monitoring: Continuous monitoring of system performance and health.
Getting Started
Navigate to the agents directory and follow the setup instructions in the README. This includes details on configuration, running agents, and examples. Most agent examples require the MCP server to be running in HTTP mode. Read the docs for each agent example for details.
Configuration
Configure the server using these environment variables (or a .env file):
| Variable | Description | Default |
|---|---|---|
MCP_TRANSPORT_TYPE |
Server transport: stdio or http. |
stdio |
MCP_SESSION_MODE |
Session mode for HTTP: stateless, stateful, or auto. |
auto |
MCP_HTTP_PORT |
Port for the HTTP server. | 3010 |
MCP_HTTP_HOST |
Host address for the HTTP server. | 127.0.0.1 |
MCP_ALLOWED_ORIGINS |
Comma-separated allowed origins for CORS. | (none) |
MCP_AUTH_MODE |
Authentication mode for HTTP: jwt, oauth, ibmi, or none. |
none |
MCP_AUTH_SECRET_KEY |
Required for jwt mode. Secret key (min 32 chars) for signing/verifying auth tokens. |
(none - MUST be set in production) |
OAUTH_ISSUER_URL |
Required for oauth mode. The issuer URL of your authorization server. |
(none) |
OAUTH_AUDIENCE |
Required for oauth mode. The audience identifier for this MCP server. |
(none) |
OPENROUTER_API_KEY |
API key for OpenRouter.ai service. | (none) |
OTEL_ENABLED |
Set to true to enable OpenTelemetry instrumentation. |
false |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |
The OTLP endpoint for exporting traces (e.g., http://localhost:4318/v1/traces). |
(none; logs to file) |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT |
The OTLP endpoint for exporting metrics (e.g., http://localhost:4318/v1/metrics). |
(none) |
TOOLS_YAML_PATH |
Path to YAML tool definitions (file or directory). Supports directories or globs. | (none) |
YAML_MERGE_ARRAYS |
When merging multiple YAML files, merge arrays (true) instead of replacing them. |
false |
YAML_ALLOW_DUPLICATE_TOOLS |
Allow duplicate tool names across merged YAML files. | false |
YAML_ALLOW_DUPLICATE_SOURCES |
Allow duplicate source names across merged YAML files. | false |
YAML_VALIDATE_MERGED |
Validate the merged YAML configuration before use. | true |
YAML_AUTO_RELOAD |
Enable automatic reloading of YAML tools when configuration files change. | true |
SELECTED_TOOLSETS |
Comma-separated list of toolset names to load/filter tools (overrides full load). | (none) |
DB2i_HOST |
IBM i Db2 for i host (Mapepire daemon or gateway host). | (none) |
DB2i_USER |
IBM i user profile for Db2 for i connections. | (none) |
DB2i_PASS |
Password for the IBM i user profile. | (none) |
DB2i_PORT |
Port for the Mapepire daemon/gateway used for Db2 for i. | 8076 |
DB2i_IGNORE_UNAUTHORIZED |
If true, skip TLS certificate verification for Mapepire (self-signed certs, etc.). |
true |
IBMI_HTTP_AUTH_ENABLED |
Required for ibmi auth mode. Enable IBM i HTTP authentication endpoints. |
false |
IBMI_AUTH_ALLOW_HTTP |
Allow HTTP requests for authentication (development only, use HTTPS in production). | false |
IBMI_AUTH_TOKEN_EXPIRY_SECONDS |
Default token lifetime in seconds for IBM i authentication tokens. | 3600 (1 hour) |
IBMI_AUTH_CLEANUP_INTERVAL_SECONDS |
How often to clean expired tokens (in seconds). | 300 (5 minutes) |
IBMI_AUTH_MAX_CONCURRENT_SESSIONS |
Maximum number of concurrent authenticated sessions allowed. | 100 |
To set the server environment variables, create a .env file in the root of this project:
cp .env.example .env
code .env
Then edit the .env file with your IBM i connection details.
IBM i HTTP Authentication (Beta)
The server supports IBM i HTTP authentication that allows clients to obtain access tokens for authenticated SQL tool execution. This enables per-user connection pooling and secure access to IBM i resources.
Authentication Flow
- Client Authentication: Clients authenticate with IBM i credentials via HTTP Basic Auth
- Token Generation: Server creates a secure Bearer token and establishes a dedicated connection pool
- Tool Execution: Subsequent tool calls use the Bearer token for authenticated execution
- Pool Management: Each token maintains its own connection pool for isolation and security
Configuration
To enable IBM i HTTP authentication, we