oracle-mcp

Un servidor de base de datos Oracle de solo lectura para el Model Context Protocol. Permite a los agentes de IA (Claude Desktop, Claude Code, Cursor, agentes de VS Code, OpenAI Agents, …) inspeccionar de forma segura esquemas Oracle heredados de gran tamaño — miles de tablas, cientos de paquetes, vistas, sinónimos, triggers, secuencias y código PL/SQL — sin modificar nunca los datos.

Está diseñado como un módulo independiente que se ejecuta junto a un "Engineering MCP" existente (GitLab / Redmine / Taiga / ERPNext): un agente, varios servidores MCP.

Modelo de seguridad en una línea: el servidor solo emite SELECT y lecturas del diccionario de datos; cada nombre de objeto se pasa como variable de enlace, el SQL de formato libre se comprueba con una protección de solo lectura de cierre por defecto, y la cuenta de base de datos debería tener concedido el rol de solo lectura. Defensa en profundidad, no una única barrera.

Tabla de contenido

• Características

• Requisitos

• Instalación

• Configuración

• Conexión con un agente

• Arquitectura

• Referencia de herramientas

• Consideraciones de seguridad

• Ejemplos

• Pruebas

• Solución de problemas

Related MCP server: safe-sql-mcp

Características

• 24 herramientas específicas que cubren búsqueda, descripción, DDL, código fuente, dependencias, índices, restricciones, triggers, sinónimos, estadísticas, objetos no válidos y ejecución de SELECT protegida.

• Solo lectura por construcción — una protección SQL que rechaza todo excepto un SELECT / WITH … SELECT único y sin comentarios.

• Variables de enlace en todas partes — los nombres de objetos y las palabras clave nunca se concatenan en el SQL.

• Acotado y seguro — límite estricto de filas (1000 por defecto), tiempo de espera por sentencia, limpieza de ResultSet.

• Agrupación de conexiones con reconexión transparente (modo grueso / Oracle Instant Client).

• Registro estructurado en stderr (marca de tiempo, herramienta, tiempo transcurrido, filas, esquema, SQL) — nunca secretos.

• Taxonomía de errores tipada — conexión / validación / SQL no válido / permiso / no encontrado / tiempo de espera / oracle.

• Fuertemente tipado (TypeScript estricto) y probado (48 pruebas unitarias para la protección y las utilidades).

Requisitos

• Node.js ≥ 18

• Oracle Instant Client instalado y en la ruta de bibliotecas (esta compilación usa el modo grueso de oracledb).

  • Windows: la carpeta de Instant Client en PATH.

  • Linux/macOS: en LD_LIBRARY_PATH / DYLD_LIBRARY_PATH, o establezca ORACLE_CLIENT_LIB_DIR.

• Acceso de red a la base de datos y una cuenta de Oracle de solo lectura (consulte Seguridad).

Instalación

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

Verifique sin una base de datos:

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

Prueba de humo contra una base de datos real (solo lectura):

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

Configuración

La configuración se realiza mediante variables de entorno. El servidor carga automáticamente un archivo .env de su propio directorio de paquete (copie .env.example → .env), de modo que los secretos residen junto al servidor y fuera de la configuración de su agente. La configuración se valida al inicio; el servidor falla rápidamente con un mensaje legible y sin secretos si falta algo.

Bases de datos (una o varias)

El servidor puede inspeccionar varias bases de datos Oracle a la vez. Cada herramienta acepta un argumento opcional database; cuando se omite, se usa la predeterminada.

Base de datos única:

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

Varias bases de datos — enumere los nombres y luego proporcione variables por nombre con el prefijo ORACLE_<NOMBRE>_ (nombre en mayúsculas, caracteres no alfanuméricos → _):

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"

Los grupos de conexiones se crean de forma diferida por base de datos: configurar diez no cuesta nada hasta que se consultan. Envuelva las contraseñas entre comillas dobles para que $/# se tomen literalmente.

Sugerencia de cadena de conexión: para una PDB use la forma de nombre de servicio host:puerto/servicio. La forma antigua host:puerto:SID no es Easy Connect — conviértala (…:puerto/servicio) o use un alias de tnsnames.

Ajustes compartidos

Conexión con un agente

oracle-mcp habla MCP a través de stdio. Añádalo junto a su Engineering MCP.

Claude Desktop / Claude Code (claude_desktop_config.json / .mcp.json) — sin secretos aquí; el servidor lee su propio .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"
    }
  }
}

Las credenciales residen en oracle-mcp/.env (ignorado por git), no en la configuración del agente. Mantener Oracle en su propio servidor (en lugar de fusionarlo en el Engineering MCP de JS) aísla la superficie de base de datos crítica para la seguridad y le permite conceder permisos e implementarlo de forma independiente.

Arquitectura

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

Estructura de carpetas

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

Por qué estas decisiones

• Paquete TS independiente, no fusionado en el Engineering MCP de JS — aísla una superficie sensible a la seguridad, permite una compilación estrictamente tipada y una implementación/concesión de permisos independiente.

• Modo grueso — elegido para esta implementación (Instant Client presente); permite el conjunto de funciones más amplio del controlador. El modo fino eliminaría la dependencia del cliente si así se deseara.

• Herramientas de metadatos declarativas — las 20 herramientas de diccionario comparten una forma segura (SQL fijo + enlaces + formato), por lo que añadir una herramienta son unas pocas líneas y las propiedades de seguridad son uniformes.

• Un único punto de paso OracleClient — cada consulta fluye a través de él, por lo que el tiempo de espera, el límite de filas, la limpieza, la asignación de errores y el registro se aplican en un único lugar.

Referencia de herramientas

Todas las herramientas llevan el prefijo oracle_. Las herramientas con ámbito de propietario aceptan un schema opcional; las herramientas de búsqueda aceptan un limit opcional (limitado a ORACLE_MAX_ROWS). Los nombres pueden indicarse como OBJETO o ESQUEMA.OBJETO.

Cómo se asignan las preguntas habituales a las herramientas

Consideraciones de seguridad

Capas (defensa en profundidad):

1. Cuenta de solo lectura (muro principal). Concede al usuario de conexión únicamente CREATE SESSION + SELECT sobre los objetos (o roles) que deba inspeccionar, además de SELECT_CATALOG_ROLE para el diccionario. El MCP debería ser incapaz de escribir independientemente de cualquier error en las capas superiores.

2. Guardia SQL (validation/sqlGuard.ts) para la única herramienta de formato libre (oracle_run_select) — falla en modo cerrado y rechaza:

   • cualquier cosa que no sea un SELECT único / WITH … SELECT;

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

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

   • paquetes peligrosos (DBMS_SQL, DBMS_SCHEDULER, DBMS_JOB, UTL_FILE, UTL_HTTP, …);

   • puntos y comas / múltiples sentencias, y todos los comentarios/sugerencias (un vector clásico de evasión);

   • analiza una proyección solo de código con el contenido de los literales de cadena en blanco, de modo que las palabras clave o los puntos y comas ocultos dentro de los literales no puedan provocar falsos positivos ni colar una segunda sentencia.

3. Variables de enlace para cada nombre de objeto / palabra clave en las 23 herramientas de metadatos — la entrada del usuario es un valor, nunca texto SQL. Los identificadores se validan además contra un conjunto estricto de caracteres.

4. Límites — tope máximo de filas (ORACLE_MAX_ROWS), callTimeout por sentencia, limpieza de ResultSet.

5. Sin fuga de secretos — las contraseñas nunca se registran; los registros van solo a stderr (stdout es el canal del MCP); el SQL tiene un tope de longitud en los registros.

Notas

• oracle_show_execution_plan ejecuta EXPLAIN PLAN, que escribe en la tabla temporal global privada de la sesión PLAN_TABLE. Eso son metadatos temporales, descartados automáticamente y disponibles incluso para cuentas de solo lectura — no se lee ni se escribe ningún dato de producción.

• La guardia es intencionadamente estricta; prefiere una herramienta de metadatos dedicada en lugar de oracle_run_select cuando exista. Un falso positivo poco frecuente (p. ej., una columna que literalmente se llame como una palabra clave no reservada) se puede solucionar con un alias.

Ejemplos

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

Pruebas

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)

Las pruebas unitarias se concentran deliberadamente en la guardia de seguridad — el conjunto de aceptación (SELECT/CTE, literales que contienen palabras prohibidas, comillas escapadas, identificadores casi-palabra clave) y el conjunto de rechazo (DML/DDL, puntos y comas, comentarios/sugerencias, PL/SQL, paquetes peligrosos, q'…', tamaño excesivo, no cadena).

Solución de problemas

Licencia

MIT.