IBM Db2 for i

Db2 for i MCP サーバー

mcp-server-db2i は、IBM i (AS/400) 上の IBM Db2 for i (Db2i) 向けの Model Context Protocol (MCP) サーバーです。Claude や Cursor などの AI アシスタントが、IBM i Access ODBC ドライバー、またはオプションで JT400 JDBC ドライバーや SSH 経由の Mapepire を通じて、IBM i データベースに対してクエリを実行し、調査できるようにします。

MCP Registry に io.github.Strom-Capital/mcp-server-db2i として掲載されています。

ウェブサイト: db2i-mcp.com。各リリースを解説するブログもあります。ドキュメント: docs.db2i-mcp.com。

アーキテクチャ

AI クライアントは、2 つの方法のいずれかで MCP サーバーに接続します。Claude Desktop、Claude Code、Cursor などのローカルクライアントは、サーバーをプロセスとして起動し、stdio を介して通信できます。リモートクライアントは /mcp で Streamable HTTP を介して接続し、OAuth 2.1 (claude.ai のカスタムコネクタ) またはベアラートークン (カスタムエージェント) でサインインします。ローカルクライアントも HTTP エンドポイントを利用できます。サーバーは、IBM i Access ODBC ドライバー (デフォルト、Java 不要)、オプションの JT400 JDBC ドライバー (DB2I_DRIVER=jt400)、または SSH のみが到達可能なシステム向けの SSH 経由の Mapepire (DB2I_DRIVER=mapepire) を使用して、Db2 for i に対して読み取り専用クエリを実行します。1 つのサーバーは、接続プロファイルを通じて複数の IBM i システムに到達でき、それぞれが独自のドライバーを持ちます。

graph LR
    subgraph clients ["AI Clients"]
        local("Claude Desktop, Claude Code, Cursor")
        remote("claude.ai connectors")
        agents("Custom Agents")
    end

    subgraph server ["MCP Server"]
        stdio["stdio"]
        http["Streamable HTTP + Auth"]
        tools[["MCP Tools"]]
        profiles{{"System profiles"}}
        odbc["IBM i Access ODBC"]
        jdbc["JT400 JDBC (optional)"]
        mapepire["Mapepire over SSH (optional)"]
    end

    subgraph prod ["IBM i: prod"]
        db2prod[("Db2 for i")]
    end

    subgraph test ["IBM i: test"]
        db2test[("Db2 for i")]
    end

    subgraph dev ["IBM i: dev"]
        db2dev[("Db2 for i")]
    end

    local -->|local process| stdio
    local -.->|remote URL| http
    remote -->|OAuth 2.1| http
    agents -->|bearer token| http
    stdio & http --> tools
    tools --> profiles
    profiles --> odbc & jdbc & mapepire
    odbc -->|ODBC| db2prod
    jdbc -->|JDBC| db2test
    mapepire -->|SSH| db2dev

機能

• 読み取り専用 SQL クエリ - SELECT 文を安全に実行します。結果は自動的に制限され、IBM i 上で長時間実行される文はクエリのタイムアウトによってキャンセルされます
• スキーマの検査 - オプションのフィルターを指定して、すべてのスキーマ／ライブラリーを一覧表示します
• テーブルのメタデータ - テーブルの一覧表示、列の説明、インデックスと制約の確認ができます
• ビューの検査 - データベースビューの一覧表示と調査ができます
• セキュリティを重視した設計 - SELECT クエリのみを許可し、認証情報は環境変数で管理します
• Docker のサポート - コンテナとして実行でき、簡単にデプロイできます
• HTTP トランスポート - トークン認証を使用した Streamable HTTP 経由の MCP により、リモートのクライアントやエージェントが接続できます
• リモートクライアント向け OAuth - ユーザー自身の IBM i プロファイルを使った OAuth 2.1 のサインイン機能を内蔵しているため、claude.ai のカスタムコネクターが接続できます。サインインページには、会社名、ロゴ、色、言語を設定できます（会社に合わせてカスタマイズ）
• 最新の MCP 仕様 - 2026-07-28 に対応しつつ、ステートレスな 2025 年世代のクライアントにも引き続きサービスを提供します
• デュアルトランスポート - stdio と HTTP を同時に実行できます
• 複数システム - DB2I_PROFILES を使って、1 つのサーバーから複数の IBM i システムに接続できます。システムごとにドライバー、認証情報、ライブラリーの許可リストを設定できます。ツールでは省略可能な system 引数を指定できます。複数システムを参照してください
• SSH のみのシステム - DB2I_DRIVER=mapepire を使うと、SSH のみが開放されている IBM i に接続できます。Mapepire は SSH セッション内で起動するため、サーバーへのインストールは不要で、ホストキーも確認されます。Mapepire ドライバーの使用を参照してください
• ツールの選択 - 個々のツールを有効または無効にできます。たとえば、execute_query を使わないメタデータ専用モードを設定できます
• 業務用 SQL ツール - YAML から読み取り専用の ERP クエリとテーブルの注記を読み込み、サーバーの起動前に mcp-server-db2i validate-tools でファイルを検証できます。業務用 SQL ツールを参照してください
• サーバーの指示 - 削除済みの行を示すフラグなど、クエリで見落としてはならないルールを、各セッションの開始時にモデルへ送信します。指示を参照してください
• チャット内のグラフ - MCP Apps に対応したホストでは、ツール呼び出しの下に並べ替え可能なグリッドとしてクエリ結果が表示され、ワンクリックでグラフを表示できます。ユーザーがグラフを求めた場合や、YAML ツールでグラフを指定した場合は、グラフが開きます。結果ビューを参照してください
• コンパクトな応答 - デフォルトではコンパクトな JSON を使用します。トークンを節約するために Markdown テーブルを使うこともできます
• 文のチェックと DDL - オブジェクト名を検証し、オブジェクトを再作成する SQL を返し、テーブルに依存する要素を一覧表示します
• カタログ検索とプロファイリング - ライブラリー全体からテーブルと列を検索し、ジャーナル記録を確認し、テーブルの行数や値の範囲をプロファイリングできます
• 列のマスキング - クエリ結果の機密列を秘匿するか、末尾 4 文字のみを表示できます。列のマスキングを参照してください
• クエリのエクスポート - クエリ結果を CSV または Excel ファイルとしてユーザーに渡せます。stdio ではファイルパス、HTTP では有効期間の短いダウンロードリンクを使います。行データがモデルを経由することはありません。クエリのエクスポートを参照してください
• 監査ログ - すべてのツール呼び出しとサインインを 1 行の JSON として記録します。SQL はデフォルトでハッシュ化されます。オプションで、各呼び出しに対するモデルの理由（MCP_TOOL_INTENT）も記録できます。監査ログを参照してください
• ツールの再読み込み - MCP_CUSTOM_TOOLS_WATCH=true を使うと、YAML ツールファイルの変更時に再読み込みできます
• リソースとプロンプト - テーブルの列と DDL を MCP リソースとして読み取り、ライブラリーの調査、テーブルの説明、クエリの作成を行うプロンプトを起点として利用できます。リソースとプロンプトを参照してください

クイックスタート

インストール

npm install -g mcp-server-db2i

デフォルトの odbc ドライバーには、マシンに unixODBC と IBM i Access ODBC Driver が必要です。Java は不要です。ほかのドライバーのパッケージはデフォルトではインストールされないため、サーバーと一緒に追加してください。

npm install -g mcp-server-db2i node-jt400              # DB2I_DRIVER=jt400, needs a JDK to install and a JRE to run
npm install -g mcp-server-db2i @ibm/mapepire-js ssh2   # DB2I_DRIVER=mapepire, when only SSH reaches the IBM i

npx を使う場合は、たとえば npx -y -p mcp-server-db2i@latest -p node-jt400 mcp-server-db2i のように -p でパッケージを指定します。jt400 パッケージと mapepire パッケージのインストールを参照してください。

または、Docker を使います。

docker build -t mcp-server-db2i .                  # odbc image (amd64; add --platform linux/amd64 on arm64)
docker build --target jt400 -t mcp-server-db2i .   # jt400 image (builds natively on arm64)

設定

IBM i の認証情報を記載した .env ファイルを作成します。

DB2I_HOSTNAME=your-ibm-i-host.com
DB2I_USERNAME=your-username
DB2I_PASSWORD=your-password
DB2I_SCHEMA=your-default-schema  # Optional

クライアントのセットアップ

MCP クライアントの設定（例：~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "db2i": {
      "command": "npx",
      "args": ["-y", "mcp-server-db2i@latest"],
      "env": {
        "DB2I_HOSTNAME": "${env:DB2I_HOSTNAME}",
        "DB2I_USERNAME": "${env:DB2I_USERNAME}",
        "DB2I_PASSWORD": "${env:DB2I_PASSWORD}"
      }
    }
  }
}

これにより環境変数の展開を使用し、設定ファイルに認証情報を記載せずに済みます。シェルのプロファイル（~/.zshrc または ~/.bashrc）で変数を設定してください。

Cursor、Claude Desktop、Claude Code、Docker のセットアップ方法については、クライアントのセットアップガイドを参照してください。

MCP クライアントをお持ちでない場合、サンプル Web アプリでは、結果テーブル、エクスポート、業務 SQL ツールを備えたブラウザチャットを利用できます。ユーザーは IBM i のユーザープロファイルでサインインし、自分のモデル API キーを使用します。

利用可能なツール

ツール	説明
execute_query	読み取り専用の SELECT クエリを実行します。結果ビュー用に chart ヒントを任意で指定できます
export_query	読み取り専用クエリの全行を CSV または XLSX ファイルに書き出します。stdio ではパス、HTTP では有効期限付きのダウンロードリンクを返します。EXPORT_ENABLED が設定されていない場合は無効です
list_schemas	スキーマ／ライブラリーを一覧表示します（フィルターは任意）
list_tables	スキーマ内のテーブルを一覧表示します（フィルターは任意）
search_tables	ライブラリー全体から名前または説明でテーブルを検索します
search_columns	ライブラリー全体から名前または説明で列を検索します
describe_table	列の詳細情報を取得します
list_views	スキーマ内のビューを一覧表示します（フィルターは任意）
list_indexes	テーブルの SQL インデックスを一覧表示します
get_table_constraints	主キー、外部キー、一意制約を取得します
list_routines	ライブラリー内の SQL プロシージャと関数を、言語、外部プログラム、SQL データアクセスとともに一覧表示します
describe_routine	プロシージャまたは関数のパラメーター、戻り値または結果列、呼び出しテンプレートを表示します
validate_query	カタログ名を含め、ステートメントを実行せずに検証します
get_object_ddl	オブジェクトを再作成する SQL DDL を返します
get_related_objects	テーブルに依存するオブジェクトを一覧表示します
get_journal_info	テーブルごとにジャーナル、イメージ、主キーを一覧表示し、レプリケーションツールが読み取れないテーブルを示します
index_advice	ライブラリー内でクエリオプティマイザーが要求したインデックスを、テンポラリーインデックスの使用状況で統合し、順位付けして一覧表示します
profile_table	保存済み統計またはスキャンから、行数、最終変更日時、列ごとの個別値数と NULL 数を取得します
get_business_context	YAML から読み込んだ業務説明、行フィルター、関連を一覧表示します
search_ibmi_services	キーワードまたはカテゴリで IBM i サービスを検索し、各サービスが追加されたリリースとクエリ例を表示します

MCP Appsに対応しているホストでは、execute_query、profile_table、業務 SQL ツールの結果が、ツール呼び出しの下にグリッドとチャートで表示されます。結果ビューを参照してください。

フィルター構文

一覧表示ツールはパターンマッチングに対応しています。

• CUST - 「CUST」を含む
• CUST* - 「CUST」で始まる
• *LOG - 「LOG」で終わる

リソースとプロンプト

MCP リソースに対応したクライアントは、ツールを呼び出さなくてもテーブルのコンテキストを読み取ることができ、入力中にライブラリー名とテーブル名を補完できます。

リソース	内容	登録条件
db2i://{schema}/{table}	カタログの列に加え、YAML の業務説明、列の注記、関連情報	describe_table が有効な場合
db2i://{schema}/{table}/ddl	テーブル、ビュー、または別名を再作成する QSYS2.GENERATE_SQL の SQL	get_object_ddl が有効な場合
db2i://business-context	MCP_CUSTOM_TOOLS から読み込まれたすべての注釈	get_business_context が有効な場合
ui://db2i/result	MCP Apps のホストがツールの結果の下に表示する結果ビュー	MCP_UI_ENABLED がオンの場合（デフォルト）

resources/list は、注釈付きのテーブルを提示します。たとえば db2i://MYLIB/ORDERS です。名前に含まれる # などの予約文字はパーセントエンコードしてください（ORD#X の場合は ORD%23X）。QUERY_ALLOWED_SCHEMAS の対象外のライブラリーは、execute_query と同じメッセージで拒否され、補完候補には許可されたライブラリーのみが表示されます。IBM i にクエリーを実行する読み取りと補完はレート制限の対象となり、読み取りは監査ログに記録されます。補完ではライブラリー名の一覧を一度取得して60秒間再利用するため、名前の入力に必要なクエリーはキー入力ごとではなく1回です。

プロンプト	引数	内容
explore_library	schema	テーブルを一覧表示し、主要なテーブルを説明して、それらの結合方法を要約します
explain_table	schema、table	行、列、キー、関連情報を平易な言葉で説明します
write_query	question、schema、table	テーブルの実際の列と YAML の関連情報を使って SELECT を1つ作成し、該当するツールが有効な場合は検証して実行します

プロンプトがモデルに呼び出すよう指示するツールが有効な場合に限り、そのプロンプトが一覧に表示されます。explore_library には list_tables と describe_table が必要で、残りの2つには describe_table が必要です。いずれも書き込みを要求しません。

使用例

IBM i 上の Iptor DC1 ERP をソースシステムとするプロジェクトで、このサーバーを使用してきました。同じパターンは、どの IBM i ERP でも利用できます。

• REST API の構築 - エージェントが ERP のテーブルとキーを見つけ、validate_query で SQL を確認し、サンプル行でテストしてから、エンドポイントを作成します。
• BI 向け ETL および ELT パイプライン - ソーステーブルのプロファイリング、get_object_ddl によるステージング用 DDL の生成、データウェアハウス向けの増分抽出とコードマッピングの草案作成を行います。
• BI へのほぼリアルタイムなレプリケーション - Fivetran などのジャーナルベースのツールがデータウェアハウスに変更をストリーミングする前に、どのテーブルがどのイメージでジャーナル記録されているかを確認します。
• アドホック分析 - Claude または Cursor を ERP に直接接続し、検証済みの Business SQL ツールと機密フィールドの列マスキングを使用して、平易な言葉で業務上の質問をします。

サンプルプロンプトと各プロンプトに対応するガードレールについては、使用例を参照してください。

使用例

接続したら、AI アシスタントに次のように尋ねることができます。

• 「'PROD' を含むすべてのスキーマを一覧表示して」
• 「スキーマ MYLIB のテーブルを表示して」
• 「MYLIB/CUSTOMERS の列を説明して」
• 「ORDERS テーブルにはどのようなインデックスがありますか？」
• 「このクエリーを実行して：SELECT * FROM MYLIB.CUSTOMERS WHERE STATUS = 'A'」
• 「MYLIB の受注ヘッダーテーブルと明細テーブルを見つけて、GET /orders/:orderNo エンドポイントを書いて」
• 「昨日以降に変更された MYLIB.ORDERHDR の行を対象とする増分抽出の草案を作成して」

ドキュメント

ガイド	説明
ツール、リソース、プロンプト	組み込みツール、フィルター構文、MCP リソース、プロンプト
HTTP トランスポート	HTTP API、認証、プロトコルバージョン
設定	すべての環境変数とドライバーオプション
セキュリティ	認証情報、レート制限、クエリ検証
業務 SQL ツール	受注、元帳、マスターデータ向けの YAML ツール
ユースケース	REST API、BI パイプライン、レプリケーション、アドホック分析
クライアントのセットアップ	Cursor、Claude、Claude Code のセットアップ
Web アプリの例	独自のモデルキーと IBM i サインインを使ったブラウザーチャット
Docker ガイド	コンテナーのデプロイ
開発	貢献方法とローカル環境のセットアップ

互換性

• IBM i V7R3 以降（V7R5 を推奨）
• validate_query と execute_query の解析チェックには QSYS2.PARSE_STATEMENT が必要です（Db2 PTF グループ SF99703 レベル 3 を適用した IBM i 7.3、または IBM i 7.4 以降）
• get_related_objects には IBM i 7.3 Technology Refresh 9、IBM i 7.4 Technology Refresh 3、またはそれ以降のリリースが必要です
• get_journal_info には QSYS2.OBJECT_STATISTICS のジャーナル列が必要です（IBM i 7.3 Technology Refresh 2 以降）
• search_ibmi_services には、Db2 for i PTF グループに含まれる QSYS2.SERVICES_INFO が必要です
• ステートメントの実行に失敗した場合の cause と recovery は SYSTOOLS.SQLCODE_INFO から取得されます。この機能がない場合、エラーには SQLSTATE、SQLCODE、メッセージのみが返されます
• Node.js 22 以降
• デフォルトの odbc ドライバーには unixODBC と IBM i Access ODBC Driver が必要です。オプションの jt400 ドライバーには、インストール時に JDK、実行時に JRE 11 以降が必要です。オプションの mapepire ドライバーには、IBM i への SSH アクセスと IBM i 上の Java 8 以降が必要です（データベースドライバーを参照）
• MCP 仕様 2026-07-28、および 2025 年頃の改訂版（2025-11-25 まで）に対応したステートレスクライアント

関連プロジェクト

• IBM ibmi-mcp-server - IBM i システム向けの IBM 公式 MCP サーバーです。YAML ベースの SQL ツール定義と AI エージェントのフレームワークを提供します。Mapepire が必要です。このプロジェクトの mapepire ドライバーは Mapepire の SSH モードを使用するため、IBM i 上で Mapepire サーバーを実行する必要はありません。

貢献

貢献を歓迎します。セットアップ手順については、開発ガイドを参照してください。

ライセンス

MIT License - 詳細は LICENSE を参照してください。

商標

IBM、IBM i、Db2 は International Business Machines Corporation の商標です。このプロジェクトは IBM と提携しておらず、IBM の承認も受けていません。

謝辞

• node-jt400 - Node.js 用 JT400 JDBC ドライバーラッパー
• node-odbc - IBM が保守する Node.js 用 ODBC バインディング
• mapepire-js - IBM が保守する Node.js 用 Mapepire クライアント
• Model Context Protocol - プロトコル仕様
• @modelcontextprotocol/server - 公式 TypeScript SDK（仕様 2026-07-28、2025 年頃のステートレスクライアント対応）