Skip to main content
Glama

oracle-mcp

読み取り専用の Oracle Database サーバーです。Model Context Protocol 向けに設計されており、AI エージェント(Claude Desktop、Claude Code、Cursor、VS Code エージェント、OpenAI Agents、…)が、数千のテーブル、数百のパッケージ、ビュー、シノニム、トリガー、シーケンス、PL/SQL ソースからなる大規模なレガシー Oracle スキーマを、データを一切変更せずに安全に調査できるようにします。

これは既存の「Engineering MCP」(GitLab / Redmine / Taiga / ERPNext)と並んで動作する独立モジュールとして設計されています。エージェント 1 つに対して MCP サーバーを複数使う構成です。

セキュリティモデルを一言で言えば: サーバーは SELECT とデータディクショナリの読み取りしか発行しません。すべてのオブジェクト名はバインド変数として渡され、自由形式の SQL はフェイルクローズの 読み取り専用ガード で検査され、さらにデータベースアカウント自体も読み取り専用にしておくべきです。単一のゲートではなく、多層防御です。


目次


Related MCP server: DB Insights MCP Server

特徴

  • 24 個の機能不能 — 検索、説明、DDL、ソース、依存関係、インデックス、制約、トリガー、シノニム、統計、無効オブジェクト、ガード付き SELECT 実行をカバーします。

  • 構造的に読み取り専用 — コメントを含まない単一の SELECT / WITH … SELECT 以外をすべて拒否する SQL ガード。

  • どこでもバインド変数 — オブジェクト名やキーワードが SQL に連結されることはありません。

  • 上限付きで安全 — 行数のハード上限(デフォルト 1000)、ステートメント単位のタイムアウト、ResultSet のクリーンアップを備えています。

  • コネクションプールと自動再接続(シックモード / Oracle Instant Client)。

  • 構造化ログを stderr に出力(タイムスタンプ、ツール、経過時間、行数、スキーマ、SQL)— シークレットは含めません。

  • 型付きエラー分類 — connection / validation / invalid-SQL / permission / not-found / timeout / oracle。

  • シンプルに型付け(TypeScript strict)、テスト済み(ガードとヘルパーのユニットテスト 48 件)。


要件

  • Node.js ≥ 18

  • Oracle Instant Client をインストールし、ライブラリパスに含めます(このビルドは oracledb の シックモード を使用します)。

    • Windows: Instant Client フォルダーを PATH 経由で。

    • Linux/macOS: LD_LIBRARY_PATH / DYLD_LIBRARY_PATH に設定するか、ORACLE_CLIENT_LIB_DIR を設定します。

  • データベースへのネットワークアクセスと、読み取り専用 Oracle アカウントが必要です(セキュリティ を参照)。


インストール

git clone <your-repo>/oracle-mcp.git
cd oracle-mcp
npm install
npm run build          # compiles src/ → dist/

データベースなしで確認:

npm test               # 48 unit tests (SQL guard, identifiers, formatting)

実データベース(読み取り専用)に対してスモークテスト:

ORACLE_USER=... ORACLE_PASSWORD=... ORACLE_CONNECT_STRING=host:port/service \
  npx tsx scripts/integration-check.ts

設定

設定は環境変数で行います。サーバーは自身のパッケージディレクトリ内の .env ファイルを自動で読み込みます(.env.example を .env にコピーします)。これによりシークレットはエージェント設定の外で、サーバーと同じ場所に置かれます。設定は起動時に検証され、不足があれば、可読性が高くシークレットを含まないメッセージでフォールクローズします。

データベース(1 つまたは複数)

サーバーは複数の Oracle データベースを同時に調査できます。すべてのツールは省略可能な database 引数を受け付け、省略時はデフォルトを使います。

単一データベース:

ORACLE_USER="readonly_user"
ORACLE_PASSWORD="change_me"
ORACLE_CONNECT_STRING="host:port/service"

複数データベース — 名前をリストし、接頭辞 ORACLE_<NAME>_ を持つ名前別の変数を指定します(名前は大文字化され、英数字以外は _ になります):

ORACLE_DATABASES=tcil,sbi_eforex,ybl
ORACLE_DEFAULT_DATABASE=tcil
ORACLE_TCIL_USER="…"        ORACLE_TCIL_PASSWORD="…"        ORACLE_TCIL_CONNECT_STRING="host:port/service"
ORACLE_SBI_EFOREX_USER="…"  ORACLE_SBI_EFOREX_PASSWORD="…"  ORACLE_SBI_EFOREX_CONNECT_STRING="host:port/service"
ORACLE_YBL_USER="…"         ORACLE_YBL_PASSWORD="…"         ORACLE_YBL_CONNECT_STRING="host:port/service"

プールはデータベースごとに遅延作成されます。プールを 10 個設定しても、クエリを実行するまでコストはかかりません。$ や # を文字どおり扱うため、パスワードは二重引用符で囲んでください。

接続文字列のヒント: PDB にはサービス名形式 host:port/service を使ってください。古い host:port:SID 形式は Easy Connect ではないため、…:port/service のように変換するか、tnsnames エイリアスを使ってください。

共有設定

変数

デフォルト

説明

ORACLE_CLIENT_LIB_DIR

(PATH から)

Instant Client の場所。未設定の場合は PATH / LD_LIBRARY_PATH から検出します。

ORACLE_TNS_ADMIN

—

使用する場合の tnsnames.ora / sqlnet.ora を含むディレクトリ。

ORACLE_MAX_ROWS

1000

どのツールでも返せる行数のハード上限(呼び出し側が要求できる最大値でもあります)。

ORACLE_QUERY_TIMEOUT_MS

15000

文ごとのタイムアウト(シックモードの callTimeout)。

ORACLE_POOL_MIN / _MAX / _INCREMENT

1 / 4 / 1

接続プールのサイズ(データベースごと)。

ORACLE_POOL_TIMEOUT

60

アイドル接続の整理(秒単位)。

ORACLE_DEFAULT_SCHEMA

—

schema 省略時に、オーナースコープのツールが使うデフォルトのオーナー。

LOG_LEVEL

info

error | warn | info | debug(ログは stderr へ)。


エージェントへの組み込み

oracle-mcp は stdio で MCP を話します。既存の Engineering MCP の隣に追加してください。

Claude Desktop / Claude Code(claude_desktop_config.json / .mcp.json)— ここにはシークレットを書く必要はありません。サーバー自身が自分の .env を読み取ります。

{
  "mcpServers": {
    "engineering": { "command": "node", "args": ["/path/to/mcp-erpnext/src/index.js"] },
    "oracle": {
      "command": "node",
      "args": ["/path/to/oracle-mcp/dist/index.js"],
      "cwd": "/path/to/oracle-mcp"
    }
  }
}

資格情報は oracle-mcp/.env(gitignore 対象)に置かれ、エージェントの設定には含めません。Oracle を独立した専用サーバーに隔離し JS の Engineering MCP にマージしないことで、セキュリティ上重要なデータベース面を分離し、独立に適用・デプロイできます。


アーキテクチャ

                        ┌──────────────────────────────────────────────┐
   AI agent  ──stdio──▶ │  index.ts  (McpServer, StdioServerTransport)  │
   (Claude/Cursor/…)    └───────────────┬──────────────────────────────┘
                                        │ registers 24 tools
                        ┌───────────────▼───────────────┐
                        │  tools/oracle/*                │  runSelect · executionPlan · ddl
                        │  (thin handlers, zod schemas)  │  · 20 declarative metadata tools
                        └───────┬───────────────┬────────┘
              guarded SQL       │               │  built SQL + binds
                    ┌───────────▼──────┐   ┌─────▼─────────────────────┐
                    │ validation/      │   │ oracle/client.ts          │
                    │ sqlGuard.ts      │   │  • timeout (callTimeout)  │
                    │ (fail-closed)    │   │  • row cap + truncation   │
                    └──────────────────┘   │  • ResultSet cleanup      │
                                           │  • error → taxonomy       │
                                           └─────┬─────────────────────┘
                                                 │ pooled connection
                                           ┌─────▼───────────────┐
                                           │ oracle/pool.ts       │  thick init · pool · reconnect
                                           └─────┬───────────────┘
                                                 ▼
                                        Oracle DB  (ALL_* dictionary + DBMS_METADATA/DBMS_XPLAN)

  cross-cutting:  config/env.ts (zod-validated)   logging/logger.ts (stderr, redacted)
                  errors.ts (typed taxonomy)       utils/ (identifiers, formatting)

フォルダー構成

oracle-mcp/
├── src/
│   ├── index.ts               # server bootstrap + graceful shutdown
│   ├── config/env.ts          # env loading & validation (zod)
│   ├── logging/logger.ts      # structured stderr logger (+ SQL redaction)
│   ├── errors.ts              # OracleMcpError + Oracle→taxonomy mapping
│   ├── types/index.ts         # shared types
│   ├── validation/sqlGuard.ts # read-only SQL guard  ◀── security core
│   ├── utils/
│   │   ├── identifiers.ts      # name validation, LIKE-pattern escaping
│   │   └── format.ts           # Markdown tables / code blocks
│   ├── oracle/
│   │   ├── pool.ts             # thick init, pool lifecycle, reconnect
│   │   └── client.ts           # the single query choke-point
│   └── tools/oracle/
│       ├── context.ts          # tool type + registration wrapper
│       ├── runSelect.ts        # oracle_run_select (guarded)
│       ├── executionPlan.ts    # oracle_show_execution_plan
│       ├── ddl.ts              # oracle_get_object_ddl / oracle_get_view
│       ├── metadataTools.ts    # 20 declarative dictionary tools
│       └── index.ts            # catalogue + registerOracleTools()
├── tests/                     # vitest unit tests
├── scripts/integration-check.ts
└── .env.example

なぜこの選択か

  • Standalone TS パッケージ(JS の Engineering MCP に統合しない) — セキュリティに敏感な領域を分離し、厳密な型チェックでビルドできるとともに、独立したデプロイと権限付与を可能にします。

  • シックモード — この環境では Instant Client が存在するため、この方式を採用しています。最も広いドライバ機能を有効にできます。必要になればシンモードにすればクライアント依存を減らせます。

  • 宣言型メタデータツール — 20 個のディクショナリツールは単一の安全な形(固定 SQL + バインド変数 + 出力形式)を共有するため、ツールの追加は数行で済み、セキュリティ特性も揃います。

  • OracleClient ひとつの経路に集約 — すべてのクエリがここを通過するため、タイムアウト、行上限、クリーンアップ、エラーマッピング、ログが一か所で強制されます。


ツールリファレンス

すべてのツールは oracle_ プリフィックスを持ちます。オーナースコープのツールは省略可能な schema を受け付けます。検索ツールは省略可能な limit を受け付けます(ORACLE_MAX_ROWS に切り詰められます)。名前は OBJECT または SCHEMA.OBJECT の形で指定できます。

ツール

主なパラメータ

説明

oracle_run_select

sql, maxRows?

ガード付きの読み取り専用 SELECT を実行します。

oracle_show_execution_plan

sql

SELECT の EXPLAIN PLAN + DBMS_XPLAN(データには触れません)。

oracle_list_schemas

—

アカウントから見えるオーナー / スキーマを列挙します。

oracle_list_tables

schema?, keyword?, limit?

テーブルを一覧表示します(フィルター可能)。

oracle_search_tables

keyword

名前にキーワードを含むテーブルを見つけます。

oracle_find_table

table_name

スキーマをまたいでテーブルを探します(シノニムを含む)。

oracle_describe_table

table_name, schema?

列、型、NULL 許容、コメントを表示します。

oracle_search_columns

column_name

列名にキーワードを含む列を検索します(例: RISK)。

oracle_find_column

column_name

その列を持つテーブルを探します(完全一致を優先)。

oracle_get_indexes

table_name

列、一意性、種類、状態を含むインデックスを取得します。

oracle_get_constraints

table_name

PK/FK/UK/CHECK 制約を、列、参照テーブル、削除規則とともに取得します。

oracle_find_triggers

table_name

テーブル上のトリガー(タイミング、イベント、状態)を見つけます。

oracle_get_object_ddl

object_name, object_type?

DBMS_METADATA による完全な CREATE DDL を取得します。

oracle_get_view

view_name

ビューの DDL と列リストを取得します。

oracle_get_package_source

package_name

パッケージの**仕様(spec)**ソースを取得します。

oracle_get_package_body

package_name

パッケージの**本体(body)**ソースを取得します。

oracle_search_package

package_name

名前のキーワードでパッケージを検索します。

oracle_search_procedure

procedure_name

プロシージャ・ファンクションを検索します(スタンドアロンとパッケージ内の両方)。

oracle_search_source

keyword, object_type?

すべての PL/SQL ソースに対する全文検索 — 参照元と呼び出し元を探します。

oracle_find_dependencies

object_name, direction?

used_by(呼び出し元)または uses(参照先)を調べます。

oracle_list_synonyms

schema?, keyword?, target_table?

シノニムを一覧表示します。target_table があると「どのオブジェクトを指すか」を表示します。

oracle_get_table_statistics

table_name

行数、ブロック数、平均行長、最終分析日時を取得します。

oracle_list_invalid_objects

schema?

INVALID 状態のオブジェクトを一覧表示します。

oracle_describe_object

object_name

ALL_OBJECTS から、そのオブジェクトの種類 / オーナー / 状態を返します。

よくある質問とツールの対応

質問

ツール

MFX_GET_MARGIN はどこで定義されていますか?

oracle_search_procedure → oracle_describe_object

パッケージ本体を表示

oracle_get_package_body

MFX_GET_MARGIN を呼び出すプロシージャをすべて見つける

oracle_find_dependencies (used_by) または oracle_search_source

mfx_transaction へのすべての参照

oracle_search_source

mfx_entity_master の内容を説明

oracle_describe_table

「risk」を含む列

oracle_search_columns

テーブルのインデックス / 外部キー / トリガー

oracle_get_indexes / oracle_get_constraints / oracle_find_triggers

このクエリの実行プランを見せて

oracle_show_execution_plan

テーブルを指すシノニム

oracle_list_synonyms (target_table)

無効オブジェクト

oracle_list_invalid_objects


セキュリティに関する考慮事項

レイヤー(多層防御):

  1. 読み取り専用アカウント(第一の壁)。 接続ユーザーには、検査が必要なオブジェクト(またはロール)に対する CREATE SESSION + SELECT のみを付与し、ディクショナリ用に SELECT_CATALOG_ROLE も付与します。MCP は、上層のいかなるバグがあっても書き込みが不可能であるべきです。

  2. SQL ガード(validation/sqlGuard.ts) — 唯一のフリーフォームツール(oracle_run_select)用で、フェイルクローズし、以下を拒否します:

    • 単独の SELECT / WITH … SELECT ではないものすべて;

    • INSERT/UPDATE/DELETE/MERGE/…、すべての DDL、GRANT/REVOKE、COMMIT/ROLLBACK;

    • PL/SQL ブロック(BEGIN/DECLARE)、CALL、EXECUTE [IMMEDIATE]、SELECT … INTO、FOR UPDATE;

    • 危険なパッケージ(DBMS_SQL、DBMS_SCHEDULER、DBMS_JOB、UTL_FILE、UTL_HTTP、…);

    • セミコロン / 複数ステートメント、およびすべてのコメント/ヒント(古典的なバイパス経路);

    • 文字列リテラルの内容をブランクにしたコードのみの射影を解析するため、リテラル内に隠されたキーワードやセミコロンは、誤検知を引き起こすことも、2 番目のステートメントを紛れ込ませることもできません。

  3. バインド変数 — 23 個のメタデータツールのすべてのオブジェクト名 / キーワードに使用。ユーザー入力は値であり、SQL テキストではありません。識別子はさらに厳格な文字セットに対して検証されます。

  4. 上限 — ハードな行数上限(ORACLE_MAX_ROWS)、ステートメントごとの callTimeout、ResultSet のクリーンアップ。

  5. 秘密情報の漏洩なし — パスワードは決してログに記録されません。ログはstderr のみに出力されます(stdout は MCP チャネル)。SQL はログ内で長さが制限されます。

注記

  • oracle_show_execution_plan は EXPLAIN PLAN を実行しますが、これはセッション専用のグローバル一時 PLAN_TABLE に書き込みます。これはスクラッチメタデータであり、自動的に破棄され、読み取り専用アカウントでも利用可能です — 本番データの読み書きは行われません。

  • ガードは意図的に厳格です。対応する専用メタデータツールが存在する場合は、oracle_run_select よりもそちらを優先してください。まれな誤検知(例:非予約キーワードと同名の列)は、エイリアスで回避できます。


例

Agent: "Describe mfx_entity_master."
 → oracle_describe_table { table_name: "MFX_ENTITY_MASTER" }

Agent: "Find every procedure that references mfx_transaction."
 → oracle_search_source { keyword: "mfx_transaction", object_type: "PACKAGE BODY" }

Agent: "Show the body of MFX_GET_MARGIN."
 → oracle_get_package_body { package_name: "MFX_GET_MARGIN" }

Agent: "What foreign keys does mfx_transaction have?"
 → oracle_get_constraints { table_name: "MFX_TRANSACTION" }

Agent: "Explain: SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7"
 → oracle_show_execution_plan { sql: "SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7" }

テスト

npm test            # unit: SQL guard (accept/reject matrix), identifiers, LIKE escaping
npm run typecheck   # tsc --noEmit
npx tsx scripts/integration-check.ts   # live smoke test (needs a DB; read-only)

単体テストは意図的にセキュリティガードに集中しています — 受理セット(SELECT/CTE、禁止語を含むリテラル、エスケープされた引用符、キーワードに類似した識別子)と拒否セット(DML/DDL、セミコロン、コメント/ヒント、PL/SQL、危険なパッケージ、q'…'、サイズ超過、非文字列)です。


トラブルシューティング

症状

原因 / 修正

DPI-1047: Cannot locate a 64-bit Oracle Client library

Instant Client が見つかりません。インストールして PATH/LD_LIBRARY_PATH に追加するか、ORACLE_CLIENT_LIB_DIR を設定してください。

ORA-12154 / ORA-12541 / ORA-12514

接続文字列の誤り / リスナーなし / サービス不明。host:port/service(SID ではなくサービス名)または有効な tnsnames エイリアスを使用してください。

ORA-01017: invalid username/password

ORACLE_USER/ORACLE_PASSWORD が誤っています。

[PERMISSION_DENIED] ORA-01031 またはディクショナリ結果が空

アカウントにオブジェクトへの SELECT または SELECT_CATALOG_ROLE がありません。読み取りアクセスを付与してください。

[VALIDATION_FAILURE] Only SELECT … permitted

SQL が単独の SELECT ではありません(またはセミコロン/コメントを含みます)。クリーンな SELECT を 1 つ送信してください。

ツールが複数のスキーマの行を返す

オブジェクト名が複数の可視スキーマに存在します。schema を渡すか(または ORACLE_DEFAULT_SCHEMA を設定して)スコープを限定してください。

エージェントに出力が見えないが stderr にログがある

正常です — ログは設計上 stderr に出力されます。stdout は MCP プロトコルのみを運びます。

起動時にサーバーが即座に終了する

stderr の行を読んでください — 設定検証が、どの環境変数が誤っているかを正確に出力します(秘密情報は含まれません)。


ライセンス

MIT。

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

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only SQL database access for AI assistants, allowing schema exploration and safe query execution without risk of data modification.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query SQL databases safely with read-only access, allowing schema discovery and SELECT queries while blocking writes and DDL operations.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only exploration of Oracle databases through natural language, providing schema inspection and safe bounded SQL query execution.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to connect to Oracle databases for schema exploration, PL/SQL source inspection, and read-only SQL queries, with optional write operations when explicitly enabled.
      -