MCP-Oracle

Español | English

MCP（Model Context Protocol）サーバーで、AIエージェントをOracleデータベースに接続します。

スキーマの探索、PL/SQLソースの読み取り、SQLの実行を行うツールを公開します。読み取り専用モードで起動し、書き込みとストアドプロシージャの呼び出しはORACLE_ALLOW_WRITE=trueで有効になります。

公式Python SDK（mcp）とpython-oracledbを使用します。Instant Client（またはORACLE_HOMEのlib/ディレクトリ）が見つかった場合はthickモードを有効にし、それ以外の場合はthinモードを使用します。thickモードは、thinモードでサポートされていないパスワードベリファイアを使用する古いインスタンス（10g/11g）で必要です。

このプロジェクトは、Oracle公式のMCPスイート（oracle/mcp）ではありません。そのリポジトリはOracle Cloudやその他のOracle製品を対象としています。このサーバーはお使いのデータベースリスナーに直接接続します。

ツール

run_queryとexecute_dmlはバインド変数（:name）を受け付けるため、SQLに値を連結する必要はありません。

Related MCP server: Oracle DB MCP Server

要件

• Python 3.9以上

• Oracleインスタンスへのアクセス（ユーザー、パスワード、ホスト、ポート、service_name）

• Oracle 10g/11g（またはthinモードが失敗する場合）：Oracle Instant ClientまたはORACLE_HOMEのlib/ディレクトリ

ローカル使用と本番環境

このREADMEはローカル使用を対象としています。CursorまたはClaude Desktopがお使いのマシンでstdio経由でserver.pyを起動します（HTTPポートは開きません）。

MCPをサーバー上で実行し続け、クライアントがネットワーク経由で接続する場合：

• Linux (RedHat)

• Windows Server

インストール

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

環境テンプレートをコピーして、値を入力してください：

cp .env.example .env

サーバーは.envを自動的に読み込みません。これらの変数はMCPクライアント設定（Cursor、Claude Desktopなど）で渡す必要があります。.envファイルはローカル参照用です。コミットしないでください。

環境変数

thickモードとthinモード

起動時にサーバーはORACLE_CLIENT_LIB_DIR（または~/oracle/instantclient）をチェックします。そのフォルダが存在する場合、oracledb.init_oracle_client()を呼び出してthickモードを使用します。

例：

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

ネイティブクライアントがない場合は、thinモードで実行されます（ほとんどの場合Oracle 12.1以上）。

Cursorでの使用

Cursorで、サーバーをMCP設定に追加します（例：~/.cursor/mcp.jsonまたはプロジェクト設定）：

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

.venvのPythonへの絶対パスを使用して、クライアントがmcpとoracledbを見つけられるようにします。

Cursorを再起動（またはMCPサーバーをリロード）して、oracle-mcpがツールリストに表示されることを確認します。

Claude Desktopでの使用

claude_desktop_config.json内：

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

手動での実行

ローカルでは、サーバーはstdio経由でMCPを話します（HTTPポートは開きません）。本番サーバーではトランスポートはHTTPです。ローカル使用と本番環境を参照してください。

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

stdin/stdoutにMCPクライアントが接続されていない場合、対話型プロンプトは表示されません。これは想定どおりです。

セキュリティ

• デフォルトではORACLE_ALLOW_WRITE=false：execute_dmlとcall_procedureはPermissionErrorで失敗します。

• run_queryはINSERT、UPDATE、DELETE、MERGE、DROP、ALTER、TRUNCATE、CREATE、GRANT、REVOKEで始まるステートメントを拒否します。

• execute_dmlはINSERT、UPDATE、DELETE、MERGEのみを受け付けます。

• SQLに値を補間する代わりに、バインド変数（:id）を使用してください。

• スキーマの探索のみが必要な場合は、最小権限のユーザーで接続してください。

• バージョン管理されたmcp.jsonに.envや資格情報をコミットしないでください。

依存関係

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0