Servidor MCP de Oracle Database

Un servidor de Model Context Protocol (MCP) que permite a GitHub Copilot y otros LLMs ejecutar consultas SQL de solo lectura contra bases de datos Oracle.

Tabla de contenidos

1. Configuración en macOS (Apple Silicon — M1/M2/M3/M4)

2. Instalación

3. Configurar VS Code

4. Opcional: Crear un usuario de solo lectura

5. Características

6. Herramientas disponibles

7. Referencia de configuración

8. Desarrollo

9. Consideraciones de seguridad

10. Solución de problemas

11. Documentación

12. Licencia

Related MCP server: MCP Server for Oracle Database

🍎 Configuración en macOS (Apple Silicon — M1/M2/M3/M4)

Esta es la ruta recomendada para usuarios de Mac. Usamos Colima como entorno de ejecución de Docker (más ligero que Docker Desktop y funciona de forma nativa en Apple Silicon) y compilamos el servidor MCP desde el código fuente.

Paso 1 — Instalar requisitos previos

Homebrew (omitir si ya está instalado):

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

Node.js v18+ vía nvm (recomendado):

# 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

O vía Homebrew:

brew install node
node --version

Colima + Docker CLI:

brew install colima docker

Paso 2 — Iniciar Colima

Colima es un entorno de ejecución de contenedores ligero para macOS; no se requiere Docker Desktop.

# 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

Si ya tienes Colima ejecutándose con menos memoria, ejecuta colima stop y luego reinicia con las banderas anteriores.

Paso 3 — Descargar e iniciar Oracle XE

El registro de contenedores de Oracle requiere una cuenta gratuita antes de poder descargar la imagen.

1. Crea una cuenta gratuita en https://container-registry.oracle.com

2. Inicia sesión, navega a Database → express y haz clic en Accept License Agreement

3. Inicia sesión desde tu terminal:

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

4. Descarga y ejecuta Oracle XE 21c:

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

5. Espera a que esté listo (tarda entre 60 y 90 segundos en el primer inicio):

# 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!

Tu base de datos ahora está disponible en:

• Cadena de conexión: localhost:1521/XE

• Contraseña de SYSTEM: OraclePwd123

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

Nota sobre el nombre del servicio: Oracle XE 21c tiene dos nombres de servicio:

• XE — la base de datos contenedora (CDB), utilizada con el usuario SYSTEM

• XEPDB1 — la base de datos conectable (PDB), utilizada para usuarios de aplicaciones regulares

Para iniciar y detener la base de datos más tarde:

docker start oracle-xe
docker stop oracle-xe

Paso 4 — Clonar y compilar el servidor MCP

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

Paso 5 — Configurar el entorno

cp .env.example .env

Edita .env para Oracle XE local (bueno para probarlo):

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

Para uso en producción, crea primero un usuario dedicado de solo lectura; consulta Crear un usuario de solo lectura.

Paso 6 — Probar el servidor

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

# Schema discovery tool tests
npm run test-discovery

Salida esperada:

✅ 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: ✅

Paso 7 — Conectar VS Code

Consulta Configurar VS Code a continuación.

📦 Instalación

Compilar desde el código fuente (Recomendado)

Te proporciona el código más reciente y te permite ejecutar la suite de pruebas para verificar que todo funcione antes de conectarte a Copilot.

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

Instalar desde npm

Si solo quieres el binario del servidor sin clonar el código fuente:

npm install -g mcp-oracle-database

🔌 Configurar VS Code

Opción A — Desde el código fuente (recomendado)

Crea .vscode/mcp.json en tu espacio de trabajo de VS Code (o añádelo a tu configuración global de MCP):

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

Reemplaza /absolute/path/to/mcp-oracle-database con la ruta real en tu máquina (ej. /Users/tu-nombre/GITHUB/mcp-oracle-database).

Opción B — Desde la instalación global de npm

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

Después de guardar la configuración, recarga VS Code y abre un chat de Copilot en modo Agente. Prueba:

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

Opcional: Crear un usuario de solo lectura

Usar SYSTEM está bien para pruebas locales, pero para cualquier base de datos real, crea un usuario dedicado de solo lectura.

Conéctate a Oracle (ej. vía sqlplus o una interfaz gráfica como 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;

Luego actualiza tu .env o configuración de MCP:

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

Características

• 🔒 Acceso de solo lectura — Utiliza un usuario de base de datos dedicado de solo lectura por seguridad

• 📡 Transporte stdio — Se comunica a través de entrada/salida estándar (no se necesita servidor HTTP)

• ⚡ Agrupación de conexiones (pooling) — Gestión eficiente de conexiones de Oracle

• 📊 Introspección de esquemas — Consulta información de tablas y columnas

• 🔍 Descubrimiento avanzado de esquemas — 5 herramientas especializadas para descubrir tablas, relaciones y patrones de datos

• 💾 Caché en memoria — Acceso rápido y repetido con caché LRU (TTL de 5 minutos)

• 📝 Registro de auditoría — Todas las consultas se registran con métricas de ejecución

• ⏱️ Protección contra tiempos de espera — Evita consultas de larga duración

• 🛡️ Límites de resultados — Límites de filas configurables para evitar problemas de memoria

• 🍎 No se necesita Oracle Client — Utiliza el modo Thin de node-oracledb (JS puro, funciona en Apple Silicon)

Arquitectura

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)

Herramientas disponibles

Herramientas principales

query_database

Ejecuta consultas SQL SELECT de solo lectura.

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

get_database_schema

Obtén la lista de tablas o detalles de columnas para una tabla específica.

{ "tableName": "ORDERS" }

Herramientas de descubrimiento de esquemas

Cinco herramientas especializadas para una introspección completa del esquema:

📖 Consulta la Documentación de descubrimiento de esquemas para obtener detalles completos y ejemplos.

Ejemplos de prompts para Copilot

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

Referencia de configuración

Todos los ajustes pueden ir en .env o como claves env en tu configuración de MCP de VS Code.

# 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

Esquemas grandes: Si tu base de datos tiene más de 500 tablas, aumenta MCP_MAX_RESPONSE_CHARS a 100000.

Desarrollo

Scripts

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

Estructura del proyecto

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

Consideraciones de seguridad

1. Usuario de solo lectura — El usuario de la base de datos solo debe tener privilegios SELECT en producción

2. Sin protección contra inyección — El servidor confía en que el LLM genere SQL válido; el usuario de solo lectura es la red de seguridad

3. Límites de consulta — Los límites de recuento de filas y tiempo de espera evitan el agotamiento de recursos

4. Registro de auditoría — Todas las consultas se registran con marcas de tiempo para su revisión

5. Uso local — Este servidor está diseñado para ejecutarse directamente en tu máquina; puede ejecutarse localmente y aun así acceder a bases de datos remotas.

Solución de problemas

Colima no se está ejecutando (macOS)

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

Problemas con el contenedor de Oracle

# 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

Error de conexión

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

• ¿Está Oracle ejecutándose? docker ps | grep oracle-xe

• Comprueba que el puerto esté mapeado: docker ps debería mostrar 0.0.0.0:1521->1521/tcp

• Prueba localhost:1521/XE para el usuario SYSTEM, localhost:1521/XEPDB1 para otros usuarios

Nombre de servicio incorrecto

Permiso denegado

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

Concede SELECT a tu usuario:

GRANT SELECT ANY TABLE TO your_user;

Se requiere inicio de sesión en el registro de contenedores de Oracle

Error: unauthorized: authentication required

1. Crea una cuenta gratuita en https://container-registry.oracle.com

2. Acepta la licencia para Database → express

3. Ejecuta docker login container-registry.oracle.com

Respuesta demasiado grande

Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS

Aumenta el límite en .env o en tu configuración de MCP de VS Code:

MCP_MAX_RESPONSE_CHARS=100000

Nota sobre el modo Thin

Este proyecto utiliza el modo Thin de node-oracledb, un controlador de JavaScript puro que no requiere Oracle Instant Client. Funciona en todas las plataformas, incluidos los Mac con Apple Silicon.

Documentación

📚 Guías de integración:

• Guía de descubrimiento de esquemas — Herramientas avanzadas de introspección de esquemas

• Referencia rápida de descubrimiento de esquemas — Hoja de trucos para todas las herramientas de descubrimiento

• Ejemplos de descubrimiento de esquemas — Ejemplos de mensajes MCP

• Guía de integración con VS Code — Configuración con GitHub Copilot

• Guía de integración con Claude Desktop — Configuración con Claude Desktop

• Guía de integración con MCP — Análisis profundo del protocolo MCP

• Descripción general de la arquitectura — Diagrama de arquitectura del sistema

• Configuración de registro — Configuración y ajustes de registro

📝 Instrucciones personalizadas:

• .github/copilot-instructions.md — Instrucciones de Copilot para todo el proyecto

• .github/instructions/ — Directrices de codificación específicas del lenguaje

Oracle es una marca registrada de Oracle Corporation. Este proyecto no está afiliado, respaldado ni patrocinado por Oracle Corporation.

Licencia

Este proyecto está disponible bajo la Licencia Pública General de GNU v3.0 (GPLv3).

🟢 Código abierto — GPLv3

Si eliges GPLv3, recibes los derechos de GPLv3 tal como están escritos, sin restricciones adicionales de campo de uso. Consulta LICENSE para ver el texto completo de la licencia y LICENSE.md para obtener una breve descripción general de la licencia.

🔵 Comercial y gubernamental — Licencia de pago

El autor puede ofrecer una licencia comercial por separado para las partes que deseen términos alternativos, como términos comerciales negociados, compromisos de garantía o derechos de distribución propietarios.

📄 Consulta LICENSE.md para obtener una descripción general de la licencia. 📄 Consulta COMMERCIAL_LICENSE.md para conocer los términos de la licencia comercial/gubernamental por separado.

Contribución

¡Las contribuciones son bienvenidas! Por favor, abre un issue o un pull request.