oracle-mcp

Ein schreibgeschützter Oracle-Datenbankserver für das Model Context Protocol. Er ermöglicht es KI-Agenten (Claude Desktop, Claude Code, Cursor, VS Code agents, OpenAI Agents, …), große Legacy-Oracle-Schemata sicher zu untersuchen — Tausende von Tabellen, Hunderte von Packages, Views, Synonyme, Trigger, Sequenzen und PL/SQL-Quellcode — ohne jemals Daten zu verändern.

Er ist als eigenständiges Modul konzipiert, das neben einem bestehenden „Engineering MCP“ (GitLab / Redmine / Taiga / ERPNext) läuft: ein Agent, mehrere MCP-Server.

Sicherheitsmodell in einem Satz: Der Server führt ausschließlich SELECT- und Data-Dictionary-Lesezugriffe aus, jeder Objektname wird als Bind-Variable übergeben, frei formuliertes SQL wird durch eine fail-closed Read-only-Wache geprüft, und das Datenbankkonto selbst sollte nur Leseberechtigung erhalten. Tiefenverteidigung, nicht ein einzelnes Tor.

Inhaltsverzeichnis

• Funktionen

• Anforderungen

• Installation

• Konfiguration

• Einbindung in einen Agenten

• Architektur

• Tool-Referenz

• Sicherheitshinweise

• Beispiele

• Tests

• Fehlerbehebung

Related MCP server: safe-sql-mcp

Funktionen

• 24 gezielte Tools für Suche, Beschreibung, DDL, Quellcode, Abhängigkeiten, Indizes, Constraints, Trigger, Synonyme, Statistiken, ungültige Objekte und abgesicherte SELECT-Ausführung.

• Konstruktionsbedingt schreibgeschützt – eine SQL-Wache, die alles ablehnt außer einem einzigen, kommentarfreien SELECT / WITH … SELECT.

• Überall Bind-Variablen – Objektnamen und Schlüsselwörter werden niemals in SQL verkettet.

• Begrenzt und sicher – harte Zeilenobergrenze (Standard 1000), Timeout pro Statement, ResultSet-Bereinigung.

• Connection-Pooling mit transparentem Wiederverbinden (Thick Mode / Oracle Instant Client).

• Strukturierte Protokollierung auf stderr (Zeitstempel, Tool, verstrichene Zeit, Zeilen, Schema, SQL) – niemals Geheimnisse.

• Typisierte Fehler-Taxonomie – Verbindungs-/Validierungs-/ungültiges-SQL-/Berechtigungs-/Nicht-gefunden-/ Timeout-/Oracle-Fehler.

• Streng typisiert (TypeScript strict) und getestet (48 Unit-Tests für die Wache und Helfer).

Anforderungen

• Node.js ≥ 18

• Oracle Instant Client installiert und im Bibliothekspfad (dieser Build verwendet oracledb im Thick Mode).

  • Windows: der Instant-Client-Ordner in PATH.

  • Linux/macOS: in LD_LIBRARY_PATH / DYLD_LIBRARY_PATH, oder ORACLE_CLIENT_LIB_DIR setzen.

• Netzwerkzugriff auf die Datenbank und ein schreibgeschütztes Oracle-Konto (siehe Sicherheitshinweise).

Installation

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

Ohne Datenbank verifizieren:

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

Smoke-Test gegen eine echte Datenbank (schreibgeschützt):

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

Konfiguration

Die Konfiguration erfolgt über Umgebungsvariablen. Der Server lädt automatisch eine .env-Datei aus seinem eigenen Paketverzeichnis (kopieren Sie .env.example → .env), sodass Geheimnisse neben dem Server und außerhalb Ihrer Agentenkonfiguration liegen. Die Konfiguration wird beim Start validiert; der Server bricht schnell mit einer lesbaren, geheimnisfreien Meldung ab, wenn etwas fehlt.

Datenbanken (eine oder mehrere)

Der Server kann mehrere Oracle-Datenbanken gleichzeitig untersuchen. Jedes Tool akzeptiert ein optionales database-Argument; wenn es weggelassen wird, wird die Standarddatenbank verwendet.

Einzelne Datenbank:

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

Mehrere Datenbanken – Namen auflisten, dann pro Namen Variablen mit dem Präfix ORACLE_<NAME>_ angeben (Name in Großbuchstaben, Nicht-Alphanumerisches → _):

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"

Pools werden lazy pro Datenbank erstellt – zehn zu konfigurieren kostet nichts, bis sie abgefragt werden. Umgeben Sie Passwörter mit doppelten Anführungszeichen, damit $/# wörtlich genommen werden.

Connect-String-Tipp: Verwenden Sie für eine PDB die Service-Name-Form host:port/service. Die ältere Form host:port:SID ist nicht Easy Connect – konvertieren Sie sie (…:port/service) oder nutzen Sie einen tnsnames-Alias.

Gemeinsame Einstellungen

Einbindung in einen Agenten

oracle-mcp spricht MCP über stdio. Fügen Sie es neben Ihrem Engineering MCP hinzu.

Claude Desktop / Claude Code (claude_desktop_config.json / .mcp.json) — hier keine Geheimnisse; der Server liest seine eigene .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"
    }
  }
}

Anmeldedaten liegen in oracle-mcp/.env (gitignored), nicht in der Agentenkonfiguration. Oracle in einem eigenen Server zu halten (anstatt es in das JS Engineering MCP zu integrieren) isoliert die sicherheitskritische Datenbankoberfläche und ermöglicht eine unabhängige Berechtigungsvergabe und Bereitstellung.

Architektur

                        ┌──────────────────────────────────────────────┐
   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)

Ordnerstruktur

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

Warum diese Entscheidungen

• Eigenständiges TS-Paket, nicht in das JS Engineering MCP integriert – isoliert eine sicherheitskritische Oberfläche, ermöglicht einen streng typisierten Build sowie unabhängige Bereitstellung/Rechtevergabe.

• Thick Mode – gewählt für dieses Deployment (Instant Client vorhanden); ermöglicht den breitesten Funktionsumfang des Treibers. Thin Mode würde die Client-Abhängigkeit entfernen, falls dies jemals gewünscht ist.

• Deklarative Metadaten-Tools – die 20 Wörterbuch-Tools teilen sich eine sichere Form (festes SQL + Binds + Format), sodass das Hinzufügen eines Tools nur wenige Zeilen umfasst und die Sicherheitseigenschaften einheitlich sind.

• Ein OracleClient-Engpass – jede Abfrage fließt durch ihn, sodass Timeout, Zeilenobergrenze, Bereinigung, Fehlerzuordnung und Protokollierung an genau einer Stelle erzwungen werden.

Tool-Referenz

Alle Tools tragen das Präfix oracle_. Owner-bezogene Tools akzeptieren ein optionales schema; Suchtools akzeptieren ein optionales limit (auf ORACLE_MAX_ROWS begrenzt). Namen können als OBJECT oder SCHEMA.OBJECT angegeben werden.

Wie häufige Fragen auf Tools abgebildet werden

Sicherheitshinweise

Ebenen (Verteidigung in der Tiefe):

1. Nur-Lese-Konto (primäre Mauer). Gewähren Sie dem Verbindungsbenutzer nur CREATE SESSION + SELECT auf die Objekte (oder Rollen), die er prüfen muss, plus SELECT_CATALOG_ROLE für das Datenwörterbuch. Das MCP sollte nicht in der Lage sein, zu schreiben, unabhängig von etwaigen Fehlern darüber.

2. SQL-Wächter (validation/sqlGuard.ts) für das eine Freiform-Tool (oracle_run_select) — er fällt geschlossen aus und lehnt ab:

   • alles, was kein einzelnes SELECT / WITH … SELECT ist;

   • INSERT/UPDATE/DELETE/MERGE/…, alle DDL, GRANT/REVOKE, COMMIT/ROLLBACK;

   • PL/SQL-Blöcke (BEGIN/DECLARE), CALL, EXECUTE [IMMEDIATE], SELECT … INTO, FOR UPDATE;

   • gefährliche Pakete (DBMS_SQL, DBMS_SCHEDULER, DBMS_JOB, UTL_FILE, UTL_HTTP, …);

   • Semikolons / mehrere Anweisungen und alle Kommentare/Hinweise (ein klassischer Bypass-Vektor);

   • es analysiert eine nur-Code-Projektion mit geleerten String-Literal-Inhalten, sodass Schlüsselwörter oder Semikolons, die in Literalen versteckt sind, weder falsch auslösen noch eine zweite Anweisung einschmuggeln können.

3. Bind-Variablen für jeden Objektnamen / jedes Schlüsselwort in den 23 Metadaten-Tools — Benutzereingaben sind ein Wert, niemals SQL-Text. Bezeichner werden zusätzlich gegen einen strengen Zeichensatz validiert.

4. Grenzen — harte Zeilenobergrenze (ORACLE_MAX_ROWS), callTimeout pro Anweisung, ResultSet-Bereinigung.

5. Kein Geheimnis-Leck — Passwörter werden nie protokolliert; Logs gehen nur an stderr (stdout ist der MCP-Kanal); SQL wird in Logs auf eine Länge begrenzt.

Hinweise

• oracle_show_execution_plan führt EXPLAIN PLAN aus, das in die sitzungsprivate globale temporäre PLAN_TABLE schreibt. Das sind temporäre Metadaten, die automatisch verworfen werden und auch für Nur-Lese-Konten verfügbar sind — es werden keine Produktionsdaten gelesen oder geschrieben.

• Der Wächter ist absichtlich streng; bevorzugen Sie ein dediziertes Metadaten-Tool gegenüber oracle_run_select, wenn eines existiert. Ein seltener Fehlalarm (z. B. eine Spalte, die wörtlich nach einem nicht reservierten Schlüsselwort benannt ist) kann mit einem Alias umgangen werden.

Beispiele

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" }

Tests

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)

Die Unit-Tests konzentrieren sich bewusst auf den Sicherheitswächter — die Akzeptanzmenge (SELECT/CTE, Literale mit verbotenen Wörtern, escaped quotes, Bezeichner nahe an Schlüsselwörtern) und die Ablehnungsmenge (DML/DDL, Semikolons, Kommentare/Hinweise, PL/SQL, gefährliche Pakete, q'…', Überlänge, Nicht-String).

Fehlerbehebung

Lizenz

MIT.