AS/400 (IBM i) MCP Server

A Model Context Protocol (MCP) server for AS/400 (IBM i) database integration with Cursor IDE. This server enables you to interact with AS/400 databases directly from Cursor IDE using natural language queries.

中文 | English

功能特點

• ✅ 執行 SQL 查詢
• ✅ 列出資料庫 Libraries (Schemas)
• ✅ 列出 Library 中的 Tables
• ✅ 獲取 Table 詳細資訊（欄位、主鍵、索引）
• ✅ 獲取資料庫系統資訊
• ✅ 支援 SSE 和 STDIO 傳輸模式
• ✅ 連線池管理
• ✅ 完整的錯誤處理和日誌記錄

系統需求

• Node.js 18.x 或更高版本
• AS/400 (IBM i) ODBC Driver (iSeries Access ODBC Driver)
• 有效的 AS/400 資料庫連線資訊

安裝

透過 npm 安裝（推薦）

npm install -g as400-mcp-server

或作為專案依賴安裝：

npm install as400-mcp-server

從源碼安裝

git clone https://github.com/j0482k6j041/as400-mcp-server.git
cd as400-mcp-server
npm install

安裝 iSeries Access ODBC Driver

在安裝此套件之前，您需要先安裝 iSeries Access ODBC Driver：

• Windows: 從 IBM 官網 下載並安裝 IBM i Access Client Solutions
• Linux: 安裝 iSeriesODBC driver
• macOS: 安裝 IBM i Access Client Solutions for Mac

快速開始

1. 配置連線資訊

有兩種配置方式：

方式 A: 在 Cursor 的 mcp.json 中配置（推薦，用於 npm 安裝）

在 Cursor 的 MCP 設定中直接配置連線資訊，無需建立 .env 檔案：

{
  "mcpServers": {
    "as400": {
      "command": "npx",
      "args": ["as400-mcp-server"],
      "env": {
        "TRANSPORT": "stdio",
        "DB_DSN": "DRIVER={iSeries Access ODBC Driver};SYSTEM=your-as400-host;UID=your-username;PWD=your-password;"
      }
    }
  }
}

方式 B: 使用 .env 檔案（用於本地開發）

建立 .env 檔案（可以參考 .env.example）：

# AS/400 Database Configuration
DB_DSN=DRIVER={iSeries Access ODBC Driver};SYSTEM=your-as400-host;UID=your-username;PWD=your-password;

# Server Configuration
PORT=3334
TRANSPORT=sse
HOST=0.0.0.0

# Connection Configuration
DB_CONNECTION_TIMEOUT=30000
DB_REQUEST_TIMEOUT=60000

# Ping Interval (ms)
PING_INTERVAL=60000

# Pool Configuration
DB_POOL_MAX=10
DB_POOL_MIN=0
DB_POOL_IDLE_TIMEOUT=30000

2. 測試連線

npm test
# 或
as400-mcp-server --test

3. 啟動伺服器

npm start
# 或
as400-mcp-server

使用方式

方式一：SSE 模式（推薦用於 Cursor）

1. 啟動 MCP 伺服器：

npm start
# 或
npm run start:sse

2. 伺服器將在 http://localhost:3334 啟動

3. 在 Cursor 中配置 MCP 連線（見下方配置說明）

方式二：STDIO 模式

TRANSPORT=stdio npm start

Cursor IDE 配置

在 Cursor 中使用此 MCP 伺服器

1. 打開 Cursor 設定
2. 找到 MCP 設定區域
3. 添加以下配置：

方式 A: 使用 SSE 傳輸（透過 HTTP）

在 Cursor 的 MCP 設定中添加：

{
  "mcpServers": {
    "as400": {
      "url": "http://localhost:3334/sse",
      "transport": "sse"
    }
  }
}

方式 B: 使用 STDIO 傳輸（透過 npx，推薦用於 npm 發布版本）

這是推薦的方式，適合從 npm 安裝的使用者：

{
  "mcpServers": {
    "as400": {
      "command": "npx",
      "args": ["as400-mcp-server"],
      "env": {
        "TRANSPORT": "stdio",
        "DB_DSN": "DRIVER={iSeries Access ODBC Driver};SYSTEM=your-as400-host;UID=your-username;PWD=your-password;"
      }
    }
  }
}

或使用分開的參數配置：

{
  "mcpServers": {
    "as400": {
      "command": "npx",
      "args": ["as400-mcp-server"],
      "env": {
        "TRANSPORT": "stdio",
        "DB_DRIVER": "{iSeries Access ODBC Driver}",
        "DB_SYSTEM": "your-as400-host",
        "DB_UID": "your-username",
        "DB_PWD": "your-password"
      }
    }
  }
}

配置說明：

• DB_DSN: 完整的 ODBC 連線字串（推薦方式）
• DB_DRIVER: ODBC Driver 名稱（預設: {iSeries Access ODBC Driver}）
• DB_SYSTEM: AS/400 系統主機名稱或 IP
• DB_UID 或 DB_USER: 資料庫使用者名稱
• DB_PWD 或 DB_PASSWORD: 資料庫密碼

注意: 如果同時提供 DB_DSN 和分開的參數，系統會優先使用 DB_DSN。

可用工具

1. as400_execute_query

執行 SQL 查詢

as400_execute_query({
  sql: "SELECT * FROM MYLIB.MYTABLE WHERE ID = ?",
  parameters: [123]
})

2. as400_list_libraries

列出所有 Libraries

as400_list_libraries({
  pattern: "PROD%" // 可選，支援萬用字元
})

3. as400_list_tables

列出指定 Library 中的 Tables

as400_list_tables({
  library: "MYLIB",
  pattern: "CUST%" // 可選
})

4. as400_table_details

獲取 Table 的詳細資訊

as400_table_details({
  library: "MYLIB",
  table: "CUSTOMERS"
})

5. as400_database_info

獲取資料庫系統資訊

as400_database_info()

API 端點

當使用 SSE 模式時，伺服器提供以下 HTTP 端點：

• GET / - 伺服器狀態
• GET /sse - SSE 連線端點
• POST /messages - 訊息處理端點
• GET /tools - 列出所有可用工具
• GET /diagnostic - 診斷資訊
• GET /query-results - 列出儲存的查詢結果
• GET /query-results/:uuid - 獲取特定查詢結果

日誌

伺服器會產生以下日誌檔案：

• combined.log - 所有日誌
• error.log - 僅錯誤日誌

故障排除

無法連接到 AS/400

1. 檢查 ODBC Driver 是否正確安裝
2. 確認連線字串中的 SYSTEM、UID、PWD 是否正確
3. 檢查網路連線和防火牆設定
4. 查看 error.log 檔案了解詳細錯誤資訊

Cursor 無法連接到 MCP 伺服器

1. 確認伺服器已啟動並運行
2. 檢查 PORT 設定是否正確
3. 確認 Cursor 的 MCP 配置正確
4. 查看伺服器日誌了解連線狀態

開發

測試連線

# 測試資料庫連線
curl http://localhost:3334/diagnostic

# 列出可用工具
curl http://localhost:3334/tools

# 檢查伺服器狀態
curl http://localhost:3334/

授權

ISC License - 詳見 LICENSE 檔案

貢獻

歡迎提交 Issue 和 Pull Request！

相關連結

• GitHub Repository
• npm Package
• Issue Tracker
• Changelog

聯絡資訊

如有問題或建議，請：

• 提交 Issue
• 或聯絡開發團隊

English

Features

• ✅ Execute SQL queries
• ✅ List database Libraries (Schemas)
• ✅ List Tables in a Library
• ✅ Get Table details (columns, primary keys, indexes)
• ✅ Get database system information
• ✅ Support for SSE and STDIO transport modes
• ✅ Connection pool management
• ✅ Complete error handling and logging

Installation

npm install -g as400-mcp-server

Quick Start

1. Create .env file with your AS/400 connection details
2. Test connection: npm test
3. Start server: npm start
4. Configure Cursor IDE to use the MCP server

Usage in Cursor IDE

Add to Cursor settings:

{
  "mcpServers": {
    "as400": {
      "url": "http://localhost:3334/sse",
      "transport": "sse"
    }
  }
}

Then use in Cursor chat:

@as400 as400_database_info()
@as400 as400_list_libraries()
@as400 as400_execute_query({ sql: "SELECT * FROM MYLIB.CUSTOMERS FETCH FIRST 10 ROWS ONLY" })

For more information, see the documentation.