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

Hilfsprogramm mit Nur-Lese-Zugriff zum Abfragen einer Oracle Database 10g von einem MCP-Server und/oder direkt vom Terminal aus per Claude Code Skill. Siehe die ursprüngliche Anforderung in requeriments.txt.

Warum es das gibt

Oracle 10g ist seit mehr als einem Jahrzehnt außerhalb des erweiterten Supports. Die modernen Oracle-Treiber (python-oracledb, node-oracledb) verwenden standardmäßig einen „Thin“-Modus, der nur das Netzwerkprotokoll von Oracle 12c und neuer spricht. Um mit einer 10g zu sprechen, muss der „Thick“-Modus erzwungen werden, gestützt auf einen lokal installierten Oracle Instant Client. Die meisten generischen Oracle-MCPs legen diese Option nicht offen, daher dieses maßgeschneiderte Hilfsprogramm.

In diesem Projekt bestätigt: Ein Oracle Instant Client 19.x im Thick-Modus stellt tatsächlich eine Verbindung zu einer Oracle Database 10g Release 10.2.0.3.0 her (es war nicht nötig, wie ursprünglich angenommen auf Instant Client 11.2 zurückzugehen).

Related MCP server: MCP Oracle Server

Architektur

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)

Sowohl das CLI als auch der MCP-Server verwenden denselben Kern (config -> db -> sql_guard/query_runner), sodass die Sicherheitsrichtlinie und die Grenzen nur einmal an einer einzigen Stelle angewendet werden.

Sicherheitsmodell (mehrstufige Verteidigung)

1. Auf Datenbankebene: Der konfigurierte Oracle-Benutzer verfügt bereits über schreibgeschützte Berechtigungen, die vom DBA erteilt wurden. Dies ist die wichtigste und tatsächliche Barriere.

2. Auf Softwareebene (src/sql_guard.py): Bevor irgendein „freies“ SQL (das über run_query/run_query_tool eintrifft) gesendet wird, wird validiert, dass es sich um eine einzige SELECT- oder WITH ... SELECT-Anweisung handelt. Jegliches INSERT/UPDATE/DELETE/MERGE, DDL, GRANT/REVOKE, PL/SQL (BEGIN, EXEC, ...) oder mit ; gestapelte Anweisungen wird abgelehnt. Die Katalogabfragen (list_tables/describe_table) durchlaufen diesen Guard nicht, da ihr SQL feststeht und von diesem Hilfsprogramm selbst geschrieben wurde; nur ihre Parameter (schema/table_name) werden als Bind-Variablen übergeben.

3. Ausführungsgrenzen: MAX_ROWS begrenzt die zurückgegebenen Zeilen (via fetchmany, das Ergebnis zeigt truncated: true, falls zutreffend) und QUERY_TIMEOUT_SECONDS bricht die Abfrage ab, wenn sie hängt (cursor.callTimeout).

4. Auditierung: Jede Ausführung (erfolgreich, mit Oracle-Fehler oder vom Guard abgelehnt) wird in logs/query_audit.log mit Benutzer, SQL und Ergebnis protokolliert.

Installation

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

Bearbeite .env mit deinen echten Daten (siehe Kommentare in .env.example): Host/Port/service_name oder SID, Benutzer und Passwort des Nur-Lese-Benutzers sowie den Pfad zu deinem Oracle Instant Client (ORACLE_INSTANT_CLIENT_DIR). Lade .env niemals in ein Repository hoch.

Verwendung

1. Konnektivität testen

.venv\Scripts\python scripts\test_connection.py

2. Abfrage-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-Server

Manuell ausführen (stdio):

.venv\Scripts\python -m src.mcp_server

Um es in einem MCP-Client (Claude Desktop, Claude Code, etc.) zu registrieren, siehe mcp-config.example.json — passe die Pfade an deine Maschine an und füge diesen Block zur mcpServers-Konfiguration des Clients hinzu.

Verfügbare Tools:

• run_query_tool(sql) — führt einen SELECT aus (Nur-Lese-Guard greift).

• list_tables(schema?) — listet Tabellen aus dem Katalog (all_tables).

• describe_table(table_name, schema?) — Spalten einer Tabelle (all_tab_columns).

4. Claude Code Skill

Siehe .claude/skills/oracle10g-query/SKILL.md. Sie wird aktiviert, wenn du Claude Code bittest, Daten aus dieser Datenbank abzufragen oder zu überprüfen; intern verwendet sie dasselbe scripts/query.py.

Zu beachtende Besonderheit von Oracle 10g

Oracle 10g unterstützt FETCH FIRST n ROWS ONLY / OFFSET nicht (Syntax 12c+). Verwende ROWNUM, um Zeilen in einer Abfrage zu begrenzen:

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