homemade-mcp-oracle-database-10g-claude

Oracle Database 10g を MCP サーバーから、および/または Claude Code のスキルを介してターミナルから直接照会するための読み取り専用ユーティリティです。元の要件は requeriments.txt を参照してください。

なぜこれが存在するのか

Oracle 10g は、10年以上前に延長サポートが終了しました。Oracle の最新ドライバ（python-oracledb、node-oracledb）は、デフォルトでは Oracle 12c 以降のネットワークプロトコルにしか対応しない "thin" モードを使用します。10g と通信するには、ローカルにインストールされた Oracle Instant Client を利用して "thick" モード を強制する必要があります。ほとんどの汎用 Oracle MCP はこのオプションを公開していないため、このオーダーメイドのユーティリティがあります。

本プロジェクトで確認済み: Oracle Instant Client 19.x の thick モードは、Oracle Database 10g Release 10.2.0.3.0 に対して接続に成功します（予想されていた Instant Client 11.2 へのダウングレードは不要でした）。

Related MCP server: MCP Oracle Server

アーキテクチャ

src/
  config.py           Carga y valida .env (conexion, Instant Client, politica)
  db.py                Conexion Oracle en modo thick (oracledb.init_oracle_client)
  sql_guard.py         Guard de solo-lectura: solo permite SELECT / WITH
  audit_log.py         Logging de auditoria (logs/query_audit.log)
  query_runner.py      Ejecuta SQL con limite de filas (MAX_ROWS), timeout y auditoria
  schema_inspector.py  Consultas de catalogo (list_tables / describe_table), SQL 10g-safe
  mcp_server.py        Servidor MCP (tools: run_query_tool, list_tables, describe_table)

scripts/
  test_connection.py   Prueba minima de conectividad (Fase 0)
  query.py             CLI de consultas (Fase 1) usado tambien por la skill

.claude/skills/oracle10g-query/SKILL.md   Skill de Claude Code (usa scripts/query.py)

CLI と MCP サーバーの両方が同じコア（config -> db -> sql_guard/query_runner）を再利用するため、セキュリティポリシーと制限は1つの場所で一度だけ適用されます。

セキュリティモデル（多層防御）

1. データベースレベル: 設定済みの Oracle ユーザーには、DBA によって付与された読み取り専用権限がすでにあります。これが主要かつ実際のバリアです。

2. ソフトウェアレベル（src/sql_guard.py）: run_query/run_query_tool で届く自由な SQL を送信する前に、それが単一の SELECT または WITH ... SELECT ステートメントであることを検証します。INSERT/UPDATE/DELETE/MERGE、DDL、GRANT/REVOKE、PL/SQL（BEGIN、EXEC、...）、または ; で連結された文はすべて拒否されます。 カタログクエリ（list_tables/describe_table）は、SQL が固定されておりこのユーティリティ自身によって書かれているため、このガードを通りません。そのパラメータ（schema/table_name）のみがバインド変数として渡されます。

3. 実行制限: MAX_ROWS は返される行数を制限し（fetchmany 経由。適用された場合は結果に truncated: true と示されます）、QUERY_TIMEOUT_SECONDS はクエリがハングした場合に中断します（cursor.callTimeout）。

4. 監査: すべての実行（成功、Oracle エラー、ガードによる拒否）は、ユーザー、SQL、結果とともに logs/query_audit.log に記録されます。

インストール

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
copy .env.example .env

.env を実際のデータで編集します（.env.example のコメントを参照）: host/ポート/service_name または SID、読み取り専用ユーザーのユーザー名とパスワード、Oracle Instant Client のパス（ORACLE_INSTANT_CLIENT_DIR）。.env をリポジトリにアップロードしないでください。

使用方法

1. 接続性を確認する

.venv\Scripts\python scripts\test_connection.py

2. クエリ用CLI

.venv\Scripts\python scripts\query.py "SELECT * FROM alguna_tabla WHERE ROWNUM <= 10" --format json
.venv\Scripts\python scripts\query.py --file consulta.sql --format table

3. MCP サーバー

手動で実行する（stdio）:

.venv\Scripts\python -m src.mcp_server

MCP クライアント（Claude Desktop、Claude Code など）に登録するには、mcp-config.example.json を参照してください。パスを自分のマシンに合わせて調整し、そのブロックをクライアントの mcpServers 設定に追加します。

公開されているツール:

• run_query_tool(sql) — SELECT を実行します（読み取り専用ガードが適用されます）。

• list_tables(schema?) — カタログのテーブルを一覧表示します（all_tables）。

• describe_table(table_name, schema?) — テーブルの列を表示します（all_tab_columns）。

4. Claude Code のスキル

.claude/skills/oracle10g-query/SKILL.md を参照してください。Claude Code にこのデータベースのデータの照会や確認を依頼すると有効になります。内部的には同じ scripts/query.py を使用します。

Oracle 10g に関する注意点

Oracle 10g は FETCH FIRST n ROWS ONLY / OFFSET（12c 以降の構文）をサポートしていません。クエリの行数を制限するには ROWNUM を使用します:

SELECT * FROM (
  SELECT col1, col2 FROM tabla ORDER BY col1
) WHERE ROWNUM <= 20