Oracle Database MCP Server

Ein Model Context Protocol (MCP) Server, der es GitHub Copilot und anderen LLMs ermöglicht, schreibgeschützte SQL-Abfragen gegen Oracle-Datenbanken auszuführen.

Inhaltsverzeichnis

1. macOS-Einrichtung (Apple Silicon — M1/M2/M3/M4)

2. Installation

3. VS Code konfigurieren

4. Optional: Einen schreibgeschützten Benutzer erstellen

5. Funktionen

6. Verfügbare Tools

7. Konfigurationsreferenz

8. Entwicklung

9. Sicherheitshinweise

10. Fehlerbehebung

11. Dokumentation

12. Lizenzierung

Related MCP server: MCP Server for Oracle Database

🍎 macOS-Einrichtung (Apple Silicon — M1/M2/M3/M4)

Dies ist der empfohlene Weg für Mac-Benutzer. Wir verwenden Colima als Docker-Laufzeitumgebung (leichter als Docker Desktop und läuft nativ auf Apple Silicon) und bauen den MCP-Server aus dem Quellcode.

Schritt 1 — Voraussetzungen installieren

Homebrew (überspringen, falls bereits installiert):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Node.js v18+ via nvm (empfohlen):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell config, then install Node
source ~/.zshrc
nvm install 20
nvm use 20
node --version    # should print v20.x.x

Oder via Homebrew:

brew install node
node --version

Colima + Docker CLI:

brew install colima docker

Schritt 2 — Colima starten

Colima ist eine leichtgewichtige Container-Laufzeitumgebung für macOS — kein Docker Desktop erforderlich.

# Start with enough resources for Oracle XE (needs at least 2GB RAM)
colima start --cpu 2 --memory 4 --disk 30

# Verify Docker is working
docker ps

Wenn Colima bereits mit weniger Speicher läuft, führen Sie colima stop aus und starten Sie es dann mit den oben genannten Flags neu.

Schritt 3 — Oracle XE abrufen und starten

Die Container-Registry von Oracle erfordert ein kostenloses Konto, bevor Sie das Image abrufen können.

1. Erstellen Sie ein kostenloses Konto unter https://container-registry.oracle.com

2. Melden Sie sich an, navigieren Sie zu Database → express und klicken Sie auf Accept License Agreement

3. Melden Sie sich über Ihr Terminal an:

docker login container-registry.oracle.com
# Enter your Oracle account email and password when prompted

4. Oracle XE 21c abrufen und ausführen:

docker run -d \
  --name oracle-xe \
  -p 1521:1521 \
  -p 5500:5500 \
  -e ORACLE_PWD=OraclePwd123 \
  container-registry.oracle.com/database/express:latest

5. Warten Sie, bis es bereit ist (dauert beim ersten Start 60–90 Sekunden):

# Poll health status — wait for "healthy"
watch -n 5 'docker inspect --format="{{.State.Health.Status}}" oracle-xe'

# Or tail the logs directly
docker logs -f oracle-xe
# Look for: DATABASE IS READY TO USE!

Ihre Datenbank ist jetzt verfügbar unter:

• Verbindungszeichenfolge: localhost:1521/XE

• SYSTEM-Passwort: OraclePwd123

• Web-UI (EM Express): http://localhost:5500/em

Hinweis zum Servicenamen: Oracle XE 21c hat zwei Servicenamen:

• XE — die Container-Datenbank (CDB), verwendet mit dem SYSTEM-Benutzer

• XEPDB1 — die steckbare Datenbank (PDB), verwendet für reguläre Anwendungsbenutzer

Um die Datenbank später zu starten und zu stoppen:

docker start oracle-xe
docker stop oracle-xe

Schritt 4 — MCP-Server klonen und bauen

git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build

Schritt 5 — Umgebung konfigurieren

cp .env.example .env

Bearbeiten Sie .env für die lokale Oracle XE (gut zum Ausprobieren):

ORACLE_CONNECTION_STRING=localhost:1521/XE
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123

Für den Produktionseinsatz erstellen Sie zuerst einen dedizierten schreibgeschützten Benutzer — siehe Einen schreibgeschützten Benutzer erstellen.

Schritt 6 — Server testen

# Core tests: connects to Oracle, queries schema and version
npm run test-client

# Schema discovery tool tests
npm run test-discovery

Erwartete Ausgabe:

✅ All tests completed successfully!

📊 Test Summary:
1. List Tools: ✅
2. List Tables (fast): ✅
3. List Tables (with counts): ✅
4. Describe Table: ✅
5. Get Table Relations: ✅
6. Get Sample Values: ✅
7. Suggest Related Tables: ✅
8. Cache Test: ✅

Schritt 7 — VS Code verbinden

Siehe VS Code konfigurieren unten.

📦 Installation

Aus dem Quellcode bauen (empfohlen)

Dies gibt Ihnen den neuesten Code und ermöglicht es Ihnen, die Testsuite auszuführen, um sicherzustellen, dass alles funktioniert, bevor Sie eine Verbindung zu Copilot herstellen.

git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build

Von npm installieren

Wenn Sie nur das Server-Binary ohne Klonen des Quellcodes möchten:

npm install -g mcp-oracle-database

🔌 VS Code konfigurieren

Option A — Aus dem Quellcode (empfohlen)

Erstellen Sie .vscode/mcp.json in Ihrem VS Code-Arbeitsbereich (oder fügen Sie es Ihrer globalen MCP-Konfiguration hinzu):

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-database/dist/server.js"],
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "system",
        "ORACLE_PASSWORD": "OraclePwd123",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

Ersetzen Sie /absolute/path/to/mcp-oracle-database durch den tatsächlichen Pfad auf Ihrem Computer (z. B. /Users/yourname/GITHUB/mcp-oracle-database).

Option B — Von npm globaler Installation

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "mcp-database-server",
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "your_user",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

Nach dem Speichern der Konfiguration laden Sie VS Code neu und öffnen Sie einen Copilot-Chat im Agent-Modus. Versuchen Sie:

"What tables are in the database?"
"Describe the HELP table"
"Show me 5 rows from the HELP table"

Optional: Einen schreibgeschützten Benutzer erstellen

Die Verwendung von SYSTEM ist für lokale Tests in Ordnung, aber für jede echte Datenbank sollten Sie einen dedizierten schreibgeschützten Benutzer erstellen.

Verbinden Sie sich mit Oracle (z. B. via sqlplus oder einer GUI wie DBeaver):

-- For Oracle XE local Docker, connect with:
-- sqlplus system/OraclePwd123@localhost:1521/XEPDB1

CREATE USER readonly_user IDENTIFIED BY secure_password;
GRANT CREATE SESSION TO readonly_user;
GRANT SELECT ANY TABLE TO readonly_user;

-- Or restrict to specific tables:
-- GRANT SELECT ON myschema.orders TO readonly_user;
-- GRANT SELECT ON myschema.customers TO readonly_user;

Aktualisieren Sie dann Ihre .env oder MCP-Konfiguration:

ORACLE_CONNECTION_STRING=localhost:1521/XEPDB1
ORACLE_USER=readonly_user
ORACLE_PASSWORD=secure_password

Funktionen

• 🔒 Schreibgeschützter Zugriff — Verwendet einen dedizierten schreibgeschützten Datenbankbenutzer aus Sicherheitsgründen

• 📡 stdio-Transport — Kommuniziert über Standard-Ein-/Ausgabe (kein HTTP-Server erforderlich)

• ⚡ Verbindungspooling — Effiziente Oracle-Verbindungsverwaltung

• 📊 Schema-Introspektion — Abfrage von Tabellen- und Spalteninformationen

• 🔍 Erweiterte Schema-Erkennung — 5 spezialisierte Tools zum Entdecken von Tabellen, Beziehungen und Datenmustern

• 💾 In-Memory-Caching — Schneller wiederholter Zugriff mit LRU-Cache (5 Minuten TTL)

• 📝 Audit-Logging — Alle Abfragen werden mit Ausführungsmetriken protokolliert

• ⏱️ Timeout-Schutz — Verhindert lang laufende Abfragen

• 🛡️ Ergebnisbegrenzungen — Konfigurierbare Zeilenlimits zur Vermeidung von Speicherproblemen

• 🍎 Kein Oracle-Client erforderlich — Verwendet node-oracledb Thin Mode (reines JS, funktioniert auf Apple Silicon)

Architektur

GitHub Copilot / LLM
        ↓ (MCP Protocol)
  MCP Client (spawns process)
        ↓ (JSON-RPC over stdio)
    MCP Server (Node.js)
        ↓ (node-oracledb Thin Mode)
  Oracle Database (read-only user)

Verfügbare Tools

Core-Tools

query_database

Führt schreibgeschützte SQL-SELECT-Abfragen aus.

{
  "query": "SELECT table_name FROM user_tables FETCH FIRST 10 ROWS ONLY",
  "maxRows": 10
}

get_database_schema

Ruft die Tabellenliste oder Spaltendetails für eine bestimmte Tabelle ab.

{ "tableName": "ORDERS" }

Schema-Erkennungs-Tools

Fünf spezialisierte Tools für eine umfassende Schema-Introspektion:

📖 Siehe Schema Discovery Documentation für vollständige Details und Beispiele.

Beispiel-Copilot-Prompts

"List all tables in the database"
"Describe the ORDERS table and its relationships"
"How many active users are there?"
"What are the top 5 products by sales this month?"
"Show me recent transactions for customer ID 12345"

Konfigurationsreferenz

Alle Einstellungen können in .env oder als env-Schlüssel in Ihrer VS Code MCP-Konfiguration vorgenommen werden.

# Oracle Database Connection
ORACLE_CONNECTION_STRING=localhost:1521/XE    # host:port/service
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123

# Connection Pool
ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10

# Query Safety
QUERY_TIMEOUT_MS=30000           # max query time in ms
MAX_ROWS_PER_QUERY=1000          # max rows Oracle will fetch
MAX_QUERY_LENGTH=50000           # max SQL length in chars
ENFORCE_READ_ONLY_QUERIES=true   # reject non-SELECT statements

# MCP Response Limits
MCP_MAX_RESPONSE_CHARS=50000     # hard cap on total response size
MCP_MAX_ROWS_IN_RESPONSE=200     # max rows per tool call response
MCP_MAX_STRING_LENGTH=500        # max chars per string field

# Logging
LOG_LEVEL=info
ENABLE_AUDIT_LOGGING=true
ENABLE_FILE_LOGGING=true
LOG_DIR=./logs
NODE_ENV=development

Große Schemata: Wenn Ihre Datenbank mehr als 500 Tabellen hat, erhöhen Sie MCP_MAX_RESPONSE_CHARS auf 100000.

Entwicklung

Skripte

npm run build          # Compile TypeScript → dist/
npm run dev            # Watch mode compilation
npm run clean          # Remove dist/
npm run typecheck      # Type-check without compiling
npm start              # Start MCP server (requires build first)
npm run test-client    # Core tool tests against live Oracle DB
npm run test-discovery # Schema discovery tool tests

Projektstruktur

mcp-oracle-database/
├── src/
│   ├── server.ts               # MCP server entry point
│   ├── client.ts               # Core test client
│   ├── test-discovery.ts       # Discovery tools test client
│   ├── config.ts               # Zod-validated configuration
│   ├── database/
│   │   ├── oracleConnection.ts # Connection pool manager
│   │   ├── queryExecutor.ts    # Query execution + safety checks
│   │   └── types.ts
│   ├── tools/
│   │   ├── queryDatabase.ts    # query_database tool
│   │   ├── getSchema.ts        # get_database_schema tool
│   │   └── discovery/          # 5 schema discovery tools + cache
│   └── utils/
│       ├── logger.ts           # Lightweight file + console logger
│       └── responseFormatter.ts # MCP response size management
├── dist/                       # Compiled output (git-ignored)
├── .env                        # Your credentials (git-ignored)
├── .env.example                # Template
└── package.json

Sicherheitshinweise

1. Schreibgeschützter Benutzer — Der Datenbankbenutzer sollte in der Produktion nur SELECT-Berechtigungen haben

2. Kein Schutz vor Injektionen — Der Server vertraut darauf, dass das LLM gültiges SQL generiert; der schreibgeschützte Benutzer ist das Sicherheitsnetz

3. Abfragebegrenzungen — Zeilenanzahl- und Timeout-Limits verhindern Ressourcenerschöpfung

4. Audit-Logging — Alle Abfragen werden mit Zeitstempeln zur Überprüfung protokolliert

5. Lokale Nutzung — Dieser Server ist dafür konzipiert, direkt auf Ihrem Computer zu laufen; er kann lokal ausgeführt werden und dennoch auf Remote-Datenbanken zugreifen.

Fehlerbehebung

Colima läuft nicht (macOS)

colima status
colima start --cpu 2 --memory 4   # Oracle needs at least 2GB RAM
docker ps                          # verify Docker is available

Probleme mit dem Oracle-Container

# Check if container exists
docker ps -a | grep oracle-xe

# View startup logs
docker logs oracle-xe

# Already exists but stopped — just start it
docker start oracle-xe

# Check health status
docker inspect --format='{{.State.Health.Status}}' oracle-xe
# Wait for: healthy

Verbindung fehlgeschlagen

Error: ORA-12545: Connect failed because target host or object does not exist

• Läuft Oracle? docker ps | grep oracle-xe

• Überprüfen Sie, ob der Port zugeordnet ist: docker ps sollte 0.0.0.0:1521->1521/tcp anzeigen

• Versuchen Sie localhost:1521/XE für den SYSTEM-Benutzer, localhost:1521/XEPDB1 für andere Benutzer

Falscher Servicename

Zugriff verweigert

Error: ORA-00942: table or view does not exist

Gewähren Sie Ihrem Benutzer SELECT-Rechte:

GRANT SELECT ANY TABLE TO your_user;

Anmeldung bei der Oracle-Container-Registry erforderlich

Error: unauthorized: authentication required

1. Erstellen Sie ein kostenloses Konto unter https://container-registry.oracle.com

2. Akzeptieren Sie die Lizenz für Database → express

3. Führen Sie docker login container-registry.oracle.com aus

Antwort zu groß

Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS

Erhöhen Sie das Limit in .env oder Ihrer VS Code MCP-Konfiguration:

MCP_MAX_RESPONSE_CHARS=100000

Hinweis zum Thin Mode

Dieses Projekt verwendet den node-oracledb Thin Mode — einen reinen JavaScript-Treiber, der keinen Oracle Instant Client erfordert. Er funktioniert auf allen Plattformen, einschließlich Apple Silicon Macs.

Dokumentation

📚 Integrationsanleitungen:

• Schema Discovery Guide — Erweiterte Schema-Introspektions-Tools

• Schema Discovery Quick Reference — Spickzettel für alle Discovery-Tools

• Schema Discovery Examples — MCP-Nachrichtenbeispiele

• VS Code Integration Guide — Einrichtung mit GitHub Copilot

• Claude Desktop Integration Guide — Einrichtung mit Claude Desktop

• MCP Integration Guide — MCP-Protokoll im Detail

• Architecture Overview — Systemarchitekturdiagramm

• Logging Configuration — Logging-Einrichtung und -Konfiguration

📝 Benutzerdefinierte Anweisungen:

• .github/copilot-instructions.md — Projektweite Copilot-Anweisungen

• .github/instructions/ — Sprachspezifische Codierungsrichtlinien

Oracle ist eine eingetragene Marke der Oracle Corporation. Dieses Projekt ist nicht mit der Oracle Corporation verbunden, wird von ihr nicht unterstützt und nicht von ihr gesponsert.

Lizenzierung

Dieses Projekt ist unter der GNU General Public License v3.0 (GPLv3) verfügbar.

🟢 Open Source — GPLv3

Wenn Sie sich für GPLv3 entscheiden, erhalten Sie die GPLv3-Rechte wie geschrieben, ohne zusätzliche Nutzungsbeschränkungen. Siehe LICENSE für den vollständigen Lizenztext und LICENSE.md für einen kurzen Lizenzüberblick.

🔵 Kommerziell & Regierung — Kostenpflichtige Lizenz

Eine separate kommerzielle Lizenz ist möglicherweise vom Autor für Parteien erhältlich, die alternative Bedingungen wünschen, wie z. B. ausgehandelte kommerzielle Bedingungen, Gewährleistungszusagen oder proprietäre Vertriebsrechte.

📄 Siehe LICENSE.md für den Lizenzüberblick. 📄 Siehe COMMERCIAL_LICENSE.md für die separaten kommerziellen/behördlichen Lizenzbedingungen.

Mitwirken

Beiträge sind willkommen! Bitte öffnen Sie ein Issue oder einen Pull Request.