Oracle Database Query MCP

oracle-database-query-mcp

Servidor MCP (Model Context Protocol) de solo lectura para bases de datos Oracle, construido con Quarkus y ejecutado en modo stdio. Permite a clientes MCP como GitHub Copilot o Claude Desktop consultar una base de datos Oracle mediante lenguaje natural.

Índice

• Herramientas disponibles
• Variables de entorno
• Instalación desde Release
• Compilar desde fuente
• Ejecutar el servidor
• Configurar en Copilot / Claude Desktop
• Desarrollo local

Herramientas disponibles (Tools)

Variables de entorno

Instalación desde Release (recomendado)

Descarga los artefactos precompilados desde la página de Releases.

Opción A — ZIP JVM (Windows / Mac / Linux con Java 21)

# Descomprimir
unzip oracle-database-query-mcp-1.0.1-jvm.zip

# Ejecutar
JDBC_URL=jdbc:oracle:thin:@host:1521/service \
JDBC_USER=usuario \
JDBC_PASSWORD=contraseña \
java -jar target/quarkus-app/quarkus-run.jar

Requiere Java 21 instalado.

Opción B — Binario nativo Linux (sin Java)

# Dar permisos de ejecución
chmod +x oracle-database-query-mcp-1.0.1-linux-x86_64

# Ejecutar directamente
JDBC_URL=jdbc:oracle:thin:@host:1521/service \
JDBC_USER=usuario \
JDBC_PASSWORD=contraseña \
./oracle-database-query-mcp-1.0.1-linux-x86_64

No requiere JVM. Arranca en milisegundos.

Opción C — Imagen Docker (nativa)

docker pull rturv/oracle-database-query-mcp:1.0.1-native

docker run -i --rm \
  -e JDBC_URL=jdbc:oracle:thin:@host:1521/ORCLPDB1 \
  -e JDBC_USER=usuario \
  -e JDBC_PASSWORD=contraseña \
  rturv/oracle-database-query-mcp:1.0.1-native

Compilar desde fuente

Requisitos: Java 21, Maven (o usa el wrapper ./mvnw).

Build JVM (estándar)

./mvnw package -DskipTests
# Artefacto: target/quarkus-app/quarkus-run.jar

Build nativo con GraalVM local

./mvnw package -Dnative -DskipTests
# Artefacto: target/*-runner

Build nativo con Docker (sin GraalVM instalado)

./mvnw clean package -Dnative -DskipTests \
  -Dquarkus.native.container-build=true \
  -Dquarkus.container-image.build=true \
  -Dquarkus.container-image.image=rturv/oracle-database-query-mcp:x.y.z-native \
  -Dquarkus.docker.dockerfile-native-path=src/main/docker/Dockerfile.native
# Artefacto: target/*-runner  +  imagen Docker local

Solo requiere Docker instalado, no GraalVM.

Ejecutar el servidor

El servidor usa stdio como transporte MCP: los clientes lo lanzan como proceso hijo y se comunican por stdin/stdout.

# JAR JVM
java -jar target/quarkus-app/quarkus-run.jar

# Binario nativo
./target/oracle-database-query-mcp-x.y.z-runner

Probar con el Inspector MCP (interfaz web)

# PowerShell
$env:JDBC_URL="jdbc:oracle:thin:@localhost:1521/XE"
$env:JDBC_USER="user"
$env:JDBC_PASSWORD="pass"
npx @modelcontextprotocol/inspector java -jar target/quarkus-app/quarkus-run.jar

Configurar en Copilot / Claude Desktop

Consulta COPILOT_CONFIG.md para instrucciones detalladas de configuración en VS Code (GitHub Copilot) y Claude Desktop.

Desarrollo local

# Modo live-coding (Quarkus Dev)
./mvnw quarkus:dev

# Tests
./mvnw test

# Build sin tests
./mvnw package -DskipTests

La Dev UI está disponible en modo dev en http://localhost:8080/q/dev/.

Arquitectura

El proyecto sigue un patrón de arquitectura hexagonal (lite):

• API (Fachada MCP): OracleMcpServer — definición de tools y entrada del protocolo.
• Service (Negocio): OracleService — validación de solo lectura y orquestación.
• Infrastructure (Persistencia): OracleRepository — acceso JDBC via Agroal.