MCP Server - Oracle DB Context

MCP サーバー - Oracle DB コンテキスト

英語 | 中文

大規模な Oracle データベースのコンテキストに応じたスキーマ情報を提供する、強力な Model Context Protocol（MCP）サーバーです。AI アシスタントが、数千ものテーブルを含むデータベースを理解して操作できるようにします。

目次

• 概要
• 機能
• 使用方法
  • VSCode Insiders で GitHub Copilot と連携する
    • オプション 1：Docker を使用する（推奨）
    • オプション 2：UV を使用する（ローカルインストール）
  • サーバーをローカルで起動する
  • 利用可能なツール
• アーキテクチャ
• 接続モード
  • シンモード（デフォルト）
  • シックモード
• システム要件
• パフォーマンスに関する考慮事項
• コントリビューション
• ライセンス
• サポート

概要

MCP Oracle DB Context サーバーは、非常に大規模な Oracle データベースを扱う際の重要な課題を解決します。数万ものテーブルやリレーションシップで AI モデルに負荷をかけずに、正確で関連性の高いデータベーススキーマ情報を提供する方法です。

データベースのスキーマ情報をインテリジェントにキャッシュして提供することで、このサーバーは AI アシスタントに次の操作を可能にします。

• 必要に応じて特定のテーブルスキーマを参照する
• 特定のパターンに一致するテーブルを検索する
• テーブル間のリレーションシップや外部キーを理解する
• データベースベンダーの情報を取得する

機能

• スマートなスキーマキャッシュ：データベースへのクエリを最小限に抑えるため、データベーススキーマのローカルキャッシュを構築して維持します
• 対象を絞ったスキーマ参照：データベース構造全体を読み込まずに、特定のテーブルのスキーマを取得します
• テーブル検索：名前のパターンマッチングでテーブルを検索します
• リレーションシップのマッピング：テーブル間の外部キーリレーションシップを把握できます
• Oracle Database のサポート：Oracle データベース専用に構築されています
• MCP 連携：VSCode の GitHub Copilot、Claude、ChatGPT、および MCP をサポートするその他の AI アシスタントとシームレスに連携します
• 読み取り専用モード：書き込み操作を防ぎながら、すべての読み取りアクセスを許可するデフォルトのセキュリティモードです

使用方法

VSCode Insiders で GitHub Copilot と連携する

VSCode Insiders でこの MCP サーバーを GitHub Copilot と使用するには、次の手順に従ってください。

1. VSCode Insiders をインストールする

   • 最新バージョンの VSCode Insiders をダウンロードしてインストールします

2. GitHub Copilot 拡張機能をインストールする

   • VSCode Insiders を開きます
   • 拡張機能マーケットプレイスに移動します
   • 「GitHub Copilot」を検索してインストールします

3. MCP サーバーを設定する

   • 推奨：Docker を使用する
   • 代替：UV を使用する

4. エージェントモードを有効にする

   • VSCode Insiders で Copilot チャットを開きます
   • 「Copilot Edits」をクリックします
   • 「Agent mode」を選択します
   • チャット入力欄の更新ボタンをクリックして、利用可能なツールを読み込みます

これらの手順を完了すると、GitHub Copilot のチャットインターフェースからすべてのデータベースコンテキストツールを利用できます。

オプション 1：Docker を使用する（推奨）

VSCode Insiders で、ユーザーまたはワークスペースの settings.json ファイルを開き、次の内容を追加します。

"mcp": {
    "inputs": [
     {
       "id": "db-password",
       "type": "promptString",
       "description": "Oracle DB Password",
       "password": true,
     }
   ],
    "servers": {
        "oracle": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "ORACLE_CONNECTION_STRING",
                "-e",
                "TARGET_SCHEMA",
                "-e",
                "CACHE_DIR",
                "-e",
                "THICK_MODE",
                "dmeppiel/oracle-mcp-server"
            ],
            "env": {
               "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
               "TARGET_SCHEMA":"",
               "CACHE_DIR":".cache",
               "THICK_MODE":"",  // Optional: set to "1" to enable thick mode
               "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and you want to set a non-default directory for client libraries
               "READ_ONLY_MODE":"1"  // Optional: set to "0" to allow write operations (default: "1" for read-only)
            }
        }
    }
}

Docker を使用する場合（推奨方式）：

• すべての依存関係はコンテナーに含まれています
• 必要に応じて、環境変数に THICK_MODE=1 を設定し、シックモードを有効にします
• THICK_MODE を使用する場合、Oracle Client ライブラリのインストール先がデフォルトの場所と異なるときは、ORACLE_CLIENT_LIB_DIR でパスを指定できます。

オプション 2：UV を使用する（ローカルインストール）

このオプションでは、プロジェクトをローカルにインストールしてセットアップする必要があります。

1. 前提条件

   • Python 3.12 以降
   • Oracle データベースへのアクセス
   • Oracle Instant Client（oracledb Python パッケージに必要）

2. UV をインストールする

   # curl を使って uv をインストールする（macOS/Linux）
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # または PowerShell を使う（Windows）
   irm https://astral.sh/uv/install.ps1 | iex
   

   uv のインストール後、必ずターミナルを再起動してください。

3. プロジェクトをセットアップする

   # リポジトリをクローンする
   git clone https://github.com/yourusername/oracle-mcp-server.git
   cd oracle-mcp-server
   
   # 仮想環境を作成して有効化する
   uv venv
   
   # 有効化する（Unix/macOS の場合）
   source .venv/bin/activate
   
   # 有効化する（Windows の場合）
   .venv\Scripts\activate
   
   # 依存関係をインストールする
   uv pip install -e .
   

4. VSCode の設定を構成する

   "mcp": {
      "inputs": [
         {
            "id": "db-password",
            "type": "promptString",
            "description": "Oracle DB Password",
            "password": true,
         }
      ],
      "servers": {
         "oracle": {
               "command": "/path/to/your/.local/bin/uv",
               "args": [
                  "--directory",
                  "/path/to/your/oracle-mcp-server",
                  "run",
                  "main.py"
               ],
               "env": {
                  "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
                  "TARGET_SCHEMA":"",
                  "CACHE_DIR":".cache",
                  "THICK_MODE":"",  // オプション：シックモードを有効にするには "1" に設定
                  "ORACLE_CLIENT_LIB_DIR":"", // オプション：シックモードを使用し、クライアントライブラリのディレクトリをデフォルト以外に指定する場合
                  "READ_ONLY_MODE":"1"  // オプション：書き込み操作を許可するには "0" に設定（デフォルトの "1" は読み取り専用）
               }
         }
      }
   }
   

• パスを、実際の uv バイナリのパスと oracle-mcp-server ディレクトリのパスに置き換えてください

両方のオプションで：

• ORACLE_CONNECTION_STRING を実際のデータベース接続文字列に置き換えてください
• TARGET_SCHEMA は省略可能です。省略した場合、ユーザーのスキーマがデフォルトで使用されます
• CACHE_DIR は省略可能です。省略した場合、MCP サーバーのルートフォルダー内の .cache がデフォルトで使用されます
• セキュリティのため、READ_ONLY_MODE はデフォルトで "1"（読み取り専用）です。書き込み操作が必要な場合にのみ "0" に設定してください

サーバーをローカルで起動する

MCP サーバーを直接実行するには：

uv run main.py

開発とテストの場合：

# Install the MCP Inspector
uv pip install mcp-cli

# Test with MCP Inspector
mcp dev main.py

# Or install in Claude Desktop
mcp install main.py

利用可能なツール

VSCode Insiders の GitHub Copilot や Claude などの AI アシスタントに接続すると、以下のツールを利用できます。

get_table_schema

特定のテーブルの列、データ型、NULL 許容性、リレーションを含む詳細なスキーマ情報を取得します。 例：

Can you show me the schema for the EMPLOYEES table?

get_tables_schema

複数のテーブルのスキーマ情報を一度に取得します。get_table_schema を複数回呼び出すより効率的です。 例：

Please provide the schemas for both EMPLOYEES and DEPARTMENTS tables.

search_tables_schema

テーブル名のパターンで検索し、そのスキーマを取得します。 例：

Find all tables that might be related to customers and show their schemas.

rebuild_schema_cache

スキーマキャッシュを強制的に再構築します。リソースを大量に消費するため、必要な場合にのみ使用してください。 例：

The database structure has changed. Could you rebuild the schema cache?

get_database_vendor_info

接続先の Oracle データベースのバージョンとスキーマに関する情報を取得します。 例：

What Oracle database version are we running?

search_columns

指定した用語に一致する列を含むテーブルを検索します。必要なデータは分かっていても、どのテーブルに含まれているか分からない場合に便利です。 例：

Which tables have columns related to customer_id?

get_pl_sql_objects

プロシージャ、関数、パッケージ、トリガーなどの PL/SQL オブジェクトに関する情報を取得します。 例：

Show me all stored procedures that start with 'CUSTOMER_'

get_object_source

PL/SQL オブジェクトのソースコードを取得します。デバッグやデータベースロジックの理解に役立ちます。 例：

Can you show me the source code for the CUSTOMER_UPDATE_PROC procedure?

get_table_constraints

テーブルのすべての制約（主キー、外部キー、一意制約、チェック制約）を取得します。 例：

What constraints are defined on the ORDERS table?

get_table_indexes

テーブルに定義されているすべてのインデックスを取得します。クエリの最適化に役立ちます。 例：

Show me all indexes on the CUSTOMERS table.

get_dependent_objects

指定したデータベースオブジェクトに依存するすべてのオブジェクトを検索します。 例：

What objects depend on the CUSTOMER_VIEW view?

get_user_defined_types

データベース内のユーザー定義型に関する情報を取得します。 例：

Show me all custom types defined in the schema.

get_related_tables

外部キーを介して指定したテーブルに関連するすべてのテーブルを取得し、参照元と参照先の両方の関係を表示します。 例：

What tables are related to the ORDERS table?

run_sql_query

SQL クエリを実行し、結果を整形されたテーブルで返します。 例：

Can you run this query for me? SELECT * FROM EMPLOYEES WHERE DEPARTMENT_ID = 10

注：デフォルトの読み取り専用モードでは、SELECT 文のみが許可されます。セキュリティ上の理由から、書き込み操作（INSERT、UPDATE、DELETE）はブロックされます。読み取り専用モードを無効にすると（READ_ONLY_MODE="0"）、このツールで読み取り操作と書き込み操作の両方を実行できます。

アーキテクチャ

この MCP サーバーは、大規模な Oracle データベース向けに最適化された 3 層アーキテクチャを採用しています。

1. DatabaseConnector Layer

   • Oracle データベースへの接続とクエリの実行を管理します
   • コネクションプーリングと再試行ロジックを実装します
   • 生の SQL 操作を処理します

2. SchemaManager Layer

   • インテリジェントなスキーマキャッシュを実装します
   • 最適化されたスキーマの検索と探索機能を提供します
   • ディスク上の永続キャッシュを管理します

3. DatabaseContext Layer

   • 高レベルの MCP ツールとインターフェースを公開します
   • 認可とアクセス制御を処理します
   • AI での利用に向けてスキーマを最適化します

接続モード

データベースコネクターは、2 つの接続モードをサポートしています。

Thin モード（デフォルト）

デフォルトでは、コネクターは純粋な Python 実装である Oracle の Thin モードを使用します。このモードには次の利点があります。

• セットアップとデプロイが簡単です
• ほとんどの基本的なデータベース操作に十分です
• さまざまな環境間での移植性に優れています

Thick モード

高度な Oracle 機能が必要な場合や、より高いパフォーマンスが求められる場合は、Thick モードを有効にできます。

• Docker を使用する場合（推奨）：Docker の環境変数に THICK_MODE=1 を設定します
• ローカルにインストールする場合：環境変数 THICK_MODE=1 をエクスポートし、システムアーキテクチャとデータベースのバージョンに互換性のある Oracle Client ライブラリがインストールされていることを確認します

ORACLE_CLIENT_LIB_DIR 環境変数を使用して、Oracle Client ライブラリのカスタムの場所を指定できます。これは特に次の場合に便利です。

• Oracle Client ライブラリが標準以外の場所にインストールされている場合
• 同じシステム上で複数の Oracle Client バージョンを使用する必要がある場合
• 標準の場所に Oracle Client をインストールする管理者権限がない場合
• 特定のデータベース機能との互換性のため、特定の Oracle Client バージョンが必要な場合

注：Docker を使用する場合、Oracle Client ライブラリはコンテナに含まれているため、インストールを気にする必要はありません（Oracle Instant Client v23.7）。コンテナは linux/arm64 と linux/amd64 の両アーキテクチャで、バージョン 19c から 23ai までの Oracle データベースをサポートしています。

読み取り専用モード

MCP サーバーは、セキュリティを高めるため、デフォルトで読み取り専用モードで動作します。これにより、データベースへの完全な読み取りアクセスを許可しながら、書き込み操作（INSERT、UPDATE、DELETE、DDL）を防止します。AI が生成したクエリによる意図しない変更を防ぎます。

設定

• デフォルト：READ_ONLY_MODE="1"（読み取り専用、安全）
• 書き込みアクセス：READ_ONLY_MODE="0"（書き込み操作を許可）

システム要件

• Python：バージョン 3.12 以上（最適なパフォーマンスに必要）
• メモリ：大規模データベース（テーブル数 10,000 以上）では、4GB 以上の利用可能な RAM
• ディスク：スキーマキャッシュ用に、最低 500MB の空き容量
• Oracle：Oracle Database 11g 以降に対応
• ネットワーク：Oracle データベースサーバーへの安定した接続

パフォーマンスに関する考慮事項

• 非常に大規模なデータベースでは、初回のキャッシュ構築に 5～10 分かかる場合があります
• 2 回目以降の起動は、通常 30 秒未満です
• キャッシュ作成後のスキーマ検索は、通常 1 秒未満で完了します
• メモリ使用量は、アクティブなスキーマのサイズに応じて増加します

貢献

貢献を歓迎します！詳細については、貢献ガイドラインをご覧ください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

サポート

問題や質問がある場合：

• この GitHub リポジトリで issue を作成してください