MCP Oracle Database Server

Servidor MCP (Model Context Protocol) para integración completa con Oracle Database. Permite ejecutar consultas SQL, comandos DDL/DML, gestionar transacciones y explorar la estructura de la base de datos directamente desde aplicaciones MCP.

🚀 Características

Consultas SQL: Ejecuta SELECT con formateo inteligente de resultados
Comandos DML/DDL: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.
Gestión de Transacciones: Soporte para transacciones manuales y automáticas
Exploración de BD: Lista tablas, describe estructuras, explora esquemas
Pool de Conexiones: Gestión eficiente de conexiones con Oracle
Compatibilidad: Soporte para versiones antiguas de Oracle (pre-12c)
Monitoreo: Health checks y estadísticas de conexión

📋 Herramientas Disponibles

`oracle_health_check`

Verifica el estado de salud de la conexión Oracle DB.

`oracle_query`

Ejecuta consultas SQL SELECT con formato de tabla o JSON.

Parámetros: sql, maxRows, formatAsTable, showMetadata

`oracle_execute`

Ejecuta comandos SQL (INSERT, UPDATE, DELETE, CREATE, etc.).

Parámetros: sql, autoCommit, showDetails

`oracle_list_tables`

Lista todas las tablas del esquema especificado.

Parámetros: owner, showDetails

`oracle_describe_table`

Muestra la estructura completa de una tabla.

Parámetros: tableName, owner, showDetails

`oracle_transaction`

Ejecuta múltiples comandos SQL en una transacción.

Parámetros: commands, rollbackOnError

`oracle_info`

Muestra información de configuración de la conexión.

🛠️ Instalación

⚠️ IMPORTANTE: Para Oracle 9g y versiones antiguas

Si está usando Oracle 9g o versiones anteriores, debe realizar estos pasos adicionales:

Configurar modo compatibilidad:

ORACLE_OLD_CRYPTO=true

Descargar Oracle Instant Client 19.26 (obligatorio para Oracle 9g):
- Windows: instantclient-basic-windows.x64-19.26.0.0.0dbru.zip
- Extraer a una carpeta (ej: C:\oracle\instantclient_19_26)
- Configurar la ruta:

ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_19_26

Configuración MCP para Oracle 9g:

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "tu-host-oracle",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "tu-servicio",
        "ORACLE_USERNAME": "usuario",
        "ORACLE_PASSWORD": "contraseña",
        "ORACLE_OLD_CRYPTO": "true",
        "ORACLE_CLIENT_LIB_DIR": "C:\\oracle\\instantclient_19_26"
      }
    }
  }
}

Instalación General MCP EN LOCAL (NO RECOMENDADO)

Instalar dependencias:

npm install

Configurar variables de entorno:

cp config.example.env .env
# Editar .env con la configuración de su base de datos

Compilar:

npm run build

⚙️ Configuración

Variables de Entorno

Variable	Descripción	Por Defecto
`ORACLE_HOST`	Host del servidor Oracle	`localhost`
`ORACLE_PORT`	Puerto de Oracle	`1521`
`ORACLE_SERVICE_NAME`	Nombre del servicio Oracle	`XE`
`ORACLE_USERNAME`	Usuario de base de datos	`hr`
`ORACLE_PASSWORD`	Contraseña de base de datos	`hr`
`ORACLE_CONNECTION_STRING`	Connection string completo (alternativo)	-
`ORACLE_OLD_CRYPTO`	OBLIGATORIO para Oracle 9g - Usar modo Thick	`false`
`ORACLE_CLIENT_LIB_DIR`	OBLIGATORIO para Oracle 9g - Ruta a Instant Client 19.26	-
`ORACLE_POOL_MIN`	Conexiones mínimas del pool	`1`
`ORACLE_POOL_MAX`	Conexiones máximas del pool	`10`
`ORACLE_POOL_TIMEOUT`	Timeout del pool en segundos	`60`
`ORACLE_FETCH_SIZE`	Filas a traer por lote	`100`
`ORACLE_STMT_CACHE_SIZE`	Tamaño cache de statements	`30`

Configuración MCP en Aplicaciones USANDO NPX (RECOMENDADO)

Ubicación del archivo de configuración

Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Para Claude Desktop (config.json)

Configuración para Oracle 9g (con Instant Client 19.26):

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "tu-host-oracle",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "tu-servicio",
        "ORACLE_USERNAME": "usuario",
        "ORACLE_PASSWORD": "contraseña",
        "ORACLE_OLD_CRYPTO": "true",
        "ORACLE_CLIENT_LIB_DIR": "C:\\oracle\\instantclient_19_26"
      }
    }
  }
}

Configuración para Oracle 12c o superior:

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "host",
        "ORACLE_PORT": "port",
        "ORACLE_SERVICE_NAME": "service",
        "ORACLE_USERNAME": "user",
        "ORACLE_PASSWORD": "password"
      }
    }
  }
}

Para instalación local

{
  "mcpServers": {
    "oracle-db": {
      "command": "node",
      "args": ["C:/workspaces/mcps/mcp-oracle-db/dist/index.js"],
      "env": {
        "ORACLE_HOST": "host",
        "ORACLE_PORT": "post",
        "ORACLE_SERVICE_NAME": "service",
        "ORACLE_USERNAME": "user",
        "ORACLE_PASSWORD": "pass",
        "ORACLE_OLD_CRYPTO": "true"
      }
    }
  }
}

Para entorno de desarrollo

{
  "mcpServers": {
    "oracle-db": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "C:/workspaces/mcps/mcp-oracle-db",
      "env": {
        "ORACLE_HOST": "localhost",
        "ORACLE_PORT": "1521", 
        "ORACLE_SERVICE_NAME": "XE",
        "ORACLE_USERNAME": "hr",
        "ORACLE_PASSWORD": "hr"
      }
    }
  }
}

Verificar configuración MCP

Después de configurar el MCP, puedes verificar que funciona correctamente:

Reiniciar la aplicación (Claude Desktop, etc.)
Usar herramienta de diagnóstico:
```
oracle_health_check()
```
Probar consulta básica:
```
oracle_query("SELECT 1 FROM DUAL")
```

Variables de Entorno Principales

# Configuración básica
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=XE
ORACLE_USERNAME=hr
ORACLE_PASSWORD=hr

# O usar connection string completo
ORACLE_CONNECTION_STRING="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XE)))"

# Para versiones antiguas de Oracle (pre-11g)
ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=/path/to/instantclient

Configuración Basada en Java Existente

Basado en la configuración Java proporcionada:

ORACLE_HOST=host
ORACLE_PORT=port
ORACLE_SERVICE_NAME=service
ORACLE_USERNAME=user
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true
ORACLE_FETCH_SIZE=100  # Basado en DataSourceCrmConfig.java

Pool de Conexiones

ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10
ORACLE_POOL_INCREMENT=1
ORACLE_POOL_TIMEOUT=60
ORACLE_STMT_CACHE_SIZE=30

🚀 Uso

Iniciar el servidor

npm run start

Modo desarrollo

npm run dev

Con inspector MCP

npm run inspector

📚 Ejemplos de Uso

Consulta Simple

SELECT * FROM employees WHERE department_id = 10

Crear Tabla

CREATE TABLE test_table (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100) NOT NULL,
    created_date DATE DEFAULT SYSDATE
)

Insertar Datos

INSERT INTO test_table (id, name) VALUES (1, 'Test Record')

Transacción Compleja

-- Comando 1
INSERT INTO customers (id, name) VALUES (1, 'Cliente Test');
-- Comando 2  
UPDATE orders SET customer_id = 1 WHERE id = 100;
-- Comando 3
DELETE FROM temp_data WHERE processed = 'Y';

🔧 Solución de Problemas

⚠️ Error Oracle 9g: Password Verifier Not Supported

Si obtiene el error "password verifier type 0x939 is not supported by node-oracledb in Thin mode" con Oracle 9g:

Solución OBLIGATORIA para Oracle 9g:

📦 Paso 1: Descargar Oracle Instant Client 19.26

# Descargar desde:
# https://download.oracle.com/otn_software/nt/instantclient/1926000/instantclient-basic-windows.x64-19.26.0.0.0dbru.zip

# Extraer a:
C:\oracle\instantclient_19_26

⚙️ Paso 2: Configurar variables obligatorias

ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_19_26

🚀 Para versiones Oracle 10g-11g: Probar sin Instant Client primero

ORACLE_OLD_CRYPTO=true

📦 Si falla con 10g-11g, instalar Oracle Instant Client

Descargar Oracle Instant Client:
- Windows: Oracle Instant Client para Windows
- Linux: Oracle Instant Client para Linux
- macOS: Oracle Instant Client para macOS
Configurar la ruta:

ORACLE_CLIENT_LIB_DIR=/path/to/instantclient

📋 Ejemplos de configuración:

Configuración básica (probar primero):

ORACLE_HOST=your-oracle-host
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=your-service
ORACLE_USERNAME=username
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true

Configuración con Instant Client (si es necesario):

ORACLE_HOST=your-oracle-host
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=your-service
ORACLE_USERNAME=username
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_19_8

❓ ¿Qué es Oracle Instant Client?

Oracle Instant Client son librerías nativas que permiten conexiones Thick (más compatibles con Oracle antiguo).

¿Cuándo es necesario?

✅ NO necesario: Si tu Oracle es 12c o superior
⚠️ Puede ser necesario: Para Oracle 10g/11g con crypto antiguo
❌ Obligatorio: Para funciones avanzadas (LDAP, conexiones wallet, etc.)

¿Cómo saber si lo necesito?

Prueba primero con ORACLE_OLD_CRYPTO=true solamente
Si obtienes errores, entonces instala Oracle Instant Client

📦 Instalación de Oracle Instant Client (Solo si es necesario)

Windows:

Descargar "Basic Package" desde Oracle Downloads
Extraer a C:\oracle\instantclient_XX_Y
Configurar: ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_XX_Y

Linux:

# Ubuntu/Debian
wget https://download.oracle.com/otn_software/linux/instantclient/XXX/instantclient-basic-linux.x64-XX.Y.Z.zip
unzip instantclient-basic-linux.x64-XX.Y.Z.zip
export ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_XX_Y

macOS:

# Descargar desde Oracle y extraer
export ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_XX_Y

Error de Conexión TNS

Verificar:

Host y puerto correctos
Servicio/SID configurado
Firewall/conectividad de red
Listener de Oracle ejecutándose

Problemas de Pool

# Ajustar configuración del pool
ORACLE_POOL_MIN=1
ORACLE_POOL_MAX=5
ORACLE_POOL_TIMEOUT=30

🧪 Testing

npm test

📖 Compatibilidad

Oracle Database: 11g, 12c, 18c, 19c, 21c
Node.js: >=18.0.0
Sistemas: Windows, Linux, macOS

🔐 Seguridad

Validación de SQL para prevenir inyecciones básicas
Gestión segura de credenciales vía variables de entorno
Soporte para conexiones SSL/TLS de Oracle
Separación de permisos entre consultas y comandos

🤝 Contribución

Fork el proyecto
Crear branch para feature (git checkout -b feature/nueva-funcionalidad)
Commit cambios (git commit -am 'Agregar nueva funcionalidad')
Push al branch (git push origin feature/nueva-funcionalidad)
Crear Pull Request

📄 Licencia

MIT License - ver LICENSE para más detalles.

🆘 Soporte

Para reportar problemas o solicitar características:

GitHub Issues: github.com/gcorroto/mcp-oracle-db/issues

MCP Oracle Database Server

MCP Oracle Database Server

🚀 Características

📋 Herramientas Disponibles

oracle_health_check

oracle_query

oracle_execute

oracle_list_tables

oracle_describe_table

oracle_transaction

oracle_info

🛠️ Instalación

⚠️ IMPORTANTE: Para Oracle 9g y versiones antiguas

Instalación General MCP EN LOCAL (NO RECOMENDADO)

⚙️ Configuración

Variables de Entorno

Configuración MCP en Aplicaciones USANDO NPX (RECOMENDADO)

Ubicación del archivo de configuración

Para Claude Desktop (config.json)

Para instalación local

Para entorno de desarrollo

Verificar configuración MCP

Variables de Entorno Principales

Configuración Basada en Java Existente

Pool de Conexiones

🚀 Uso

Iniciar el servidor

Modo desarrollo

Con inspector MCP

📚 Ejemplos de Uso

Consulta Simple

Crear Tabla

Insertar Datos

Transacción Compleja

🔧 Solución de Problemas

⚠️ Error Oracle 9g: Password Verifier Not Supported

📦 Paso 1: Descargar Oracle Instant Client 19.26

⚙️ Paso 2: Configurar variables obligatorias

🚀 Para versiones Oracle 10g-11g: Probar sin Instant Client primero

📦 Si falla con 10g-11g, instalar Oracle Instant Client

📋 Ejemplos de configuración:

❓ ¿Qué es Oracle Instant Client?

📦 Instalación de Oracle Instant Client (Solo si es necesario)

Error de Conexión TNS

Problemas de Pool

🧪 Testing

📖 Compatibilidad

🔐 Seguridad

🤝 Contribución

📄 Licencia

🆘 Soporte

📚 Recursos Adicionales

Related Servers

CrateDB MCP Server

BigQuery

MongoDB MCP Server

MotherDuck

Snowflake

Token Metrics

AlibabaCloud DMS MCP Server

MySQL

Astro MCP

microCMS MCP Server

`oracle_health_check`

`oracle_query`

`oracle_execute`

`oracle_list_tables`

`oracle_describe_table`

`oracle_transaction`

`oracle_info`