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

Server	Summary	Actions
Snowflake	A Model Context Protocol (MCP) server that provides Claude access to Snowflake databases. / 一个为 C...	View
Mongo-MCP	English \| 简体中文	View
microCMS MCP Server	microCMS のMCP（Model Context Protocol）サーバーです。 ClaudeなどのAIアシスタントがmicroCMSのコンテ...	View
NocoDB		View
Microsoft SQL Server		View
Neon MCP Server		View