Skip to main content
Glama
homemade-mcp-oracle-database-10g-claude

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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables GitHub Copilot and other LLMs to execute read-only SQL queries against Oracle databases with secure connection pooling and schema introspection capabilities.
      2
      110 npm
      5
      AGPL 3.0
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Oracle databases through MCP by executing SELECT queries, describing table structures, and listing available tables with secure, read-only access.
      3
      2
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only SQL querying and schema inspection across MSSQL, PostgreSQL, and MySQL databases via MCP tools.
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to query PostgreSQL, MySQL, SQL Server, Oracle, and MongoDB databases through MCP with read-only, audited access.
      3
      AGPL 3.0