Esta es una guía para utilizar sqlcl como MCP de aplicativos de desarrollo que utilizan modelos avanzados de lenguaje como puede ser claude code, opencode, qwencode; O también por agentes de IA como openclaw y hermes. El MCP nos permite trabajar directamente en la base de datos sin tener que copiar y pegar lo que estamos haciendo a un cliente de base de datos esto brinda mucha potencia y flexbilidad.
Esta guía la he creado con ubuntu y un oracle autonomous database, lo hice así para mostrar que no es necesario estar dentro de un ecosistema oracle para utilizar la base de datos ADB.
Bajar SQLcl del sitio de Oracle a un directorio de trabajo en la máquina.
ubuntu@server01:~/stage$ wget https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-latest.zip
SQLcl necesita Oracle Java 17 o 21. Se puede usar OpenJDK 21.
ubuntu@server01:~/stage$ sudo apt install openjdk-21-jre-headless ubuntu@server01:~/stage$ java -version openjdk version "21.0.10" 2026-01-20 OpenJDK Runtime Environment (build 21.0.10+7-Ubuntu-124.04) OpenJDK 64-Bit Server VM (build 21.0.10+7-Ubuntu-124.04, mixed mode, sharing)
Descomprimimos SQLcl — se genera un directorio llamado sqlcl. Probamos que funcione.
ubuntu@server01:~$ unzip ./stage/sqlcl-latest.zip
ubuntu@server01:~$ cd sqlcl/bin && ./sql
SQLcl: Release 26.1 Production on Thu Apr 16 17:08:26 2026
Copyright (c) 1982, 2026, Oracle. All rights reserved.
Username? ('')
Agregamos SQLcl al PATH para no tener que llamarlo con la ruta completa.
export PATH="$HOME/.local/bin:$PATH":/home/ubuntu/sqlcl/bin
Para conectarnos a una ADB necesitamos el wallet de la base de datos. Se descarga desde la consola de OCI en la sección ADB.
ubuntu@server01:~$ mkdir -p ~/.oracle/wallets/dbdevel ubuntu@server01:~$ cd .oracle/wallets/dbdevel ubuntu@server01:~/.oracle/wallets/dbdevel$ unzip /home/ubuntu/stage/Wallet_dbdevel.zip Archive: /home/ubuntu/stage/Wallet_dbdevel.zip inflating: ewallet.pem inflating: README inflating: cwallet.sso inflating: tnsnames.ora inflating: truststore.jks inflating: ojdbc.properties inflating: sqlnet.ora inflating: ewallet.p12 inflating: keystore.jks ubuntu@server01:~/.oracle/wallets/dbdevel$ ls -l total 48 -rw-rw-r-- 1 ubuntu ubuntu 3431 Apr 16 17:21 README -rw-rw-r-- 1 ubuntu ubuntu 6357 Apr 16 17:21 cwallet.sso -rw-rw-r-- 1 ubuntu ubuntu 6312 Apr 16 17:21 ewallet.p12 -rw-rw-r-- 1 ubuntu ubuntu 7097 Apr 16 17:21 ewallet.pem -rw-rw-r-- 1 ubuntu ubuntu 3190 Apr 16 17:21 keystore.jks -rw-rw-r-- 1 ubuntu ubuntu 691 Apr 16 17:21 ojdbc.properties -rw-rw-r-- 1 ubuntu ubuntu 113 Apr 16 17:21 sqlnet.ora -rw-rw-r-- 1 ubuntu ubuntu 2711 Apr 16 17:21 tnsnames.ora -rw-rw-r-- 1 ubuntu ubuntu 3021 Apr 16 17:21 truststore.jks
Agregamos la variable TNS_ADMIN para que SQLcl encuentre el wallet automáticamente.
export TNS_ADMIN=~/.oracle/wallets/dbdevel
ubuntu@server01:~$ source .bashrc
La información de conexión está dentro del sqlnet.ora que está dentro del wallet. Es necesario verificar que apunte al directorio correcto donde está el wallet.
ubuntu@server01:~/.oracle/wallets/dbdevel$ cat sqlnet.ora WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="/home/ubuntu/.oracle/wallets/dbdevel"))) SSL_SERVER_DN_MATCH=no
Las conexiones están dentro del tnsnames.ora que está en el wallet. Podemos hacer un cat y ver toda la lista de conexiones disponibles.
ubuntu@server01:~/.oracle/wallets/dbdevel$ cat tnsnames.ora
Creamos un usuario en la base para poder hacer pruebas. Lo podemos crear en la consola de OCI en el ADB en las Database Actions → SQL.
-- Usuario de aplicativo para pruebas en ADB CREATE USER app_test IDENTIFIED BY "PruebasApp#2025"; ALTER USER app_test QUOTA UNLIMITED ON DATA; GRANT CREATE SESSION TO app_test; GRANT CREATE TABLE TO app_test; GRANT CREATE VIEW TO app_test; GRANT CREATE SEQUENCE TO app_test; GRANT CREATE PROCEDURE TO app_test; GRANT CREATE TRIGGER TO app_test; GRANT CREATE TYPE TO app_test; GRANT CREATE SYNONYM TO app_test; GRANT CREATE DATABASE LINK TO app_test; GRANT CREATE JOB TO app_test;
Nos conectamos a la base de datos con el usuario recién creado.
ubuntu@server01:~$ sql app_test@dbdevel_medium SQLcl: Release 26.1 Production on Thu Apr 16 17:40:53 2026 Copyright (c) 1982, 2026, Oracle. All rights reserved. Password? (**********?) *************** Connected to: Oracle AI Database 26ai Enterprise Edition Release 23.26.1.2.0 - Production Version 23.26.1.2.0 SQL>
Agregamos un conector guardado — esto es importante porque es el que usa el MCP server de SQLcl. Las conexiones quedan almacenadas en ~/.dbtools.
ubuntu@server01:~$ sql /nolog SQLcl: Release 26.1 Production on Thu Apr 16 17:49:41 2026 Copyright (c) 1982, 2026, Oracle. All rights reserved. SQL> conn -save dbdevel_apptest -savepwd app_test/PruebasApp#2025@dbdevel_medium Name: dbdevel_apptest Connect String: dbdevel_medium User: app_test Password: ****** Connected. SQL> connmgr list . └── dbdevel_apptest SQL> connmgr show dbdevel_apptest Name: dbdevel_apptest Connect String: dbdevel_medium User: app_test Password: ****** SQL> exit Disconnected from Oracle AI Database 26ai Enterprise Edition Release 23.26.1.2.0 - Production ubuntu@server01:~$ sql -name dbdevel_apptest SQLcl: Release 26.1 Production on Thu Apr 16 17:50:22 2026 Copyright (c) 1982, 2026, Oracle. All rights reserved. Connected to: Oracle AI Database 26ai Enterprise Edition Release 23.26.1.2.0 - Production Version 23.26.1.2.0
Probamos que funcione el MCP server iniciando SQLcl en modo MCP.
ubuntu@server01:~$ sql -mcp ---------- MCP SERVER STARTUP ---------- MCP Server started successfully on Thu Apr 16 17:52:11 UTC 2026 Press Ctrl+C to stop the server ----------------------------------------
Instalamos Claude Code, opencode, qwen-code o cualquier herramienta de asistencia de consola para codificación. En este caso usamos Claude Code. Documentación: https://code.claude.com/docs/en/quickstart
ubuntu@server01:~$ curl -fsSL https://claude.ai/install.sh | bash Setting up Claude Code... ✔ Claude Code successfully installed! Version: 2.1.111 Location: ~/.local/bin/claude Next: Run claude --help to get started ✅ Installation complete!
Agregamos el MCP de SQLcl a Claude Code y verificamos que aparezca conectado.
ubuntu@server01:~/claude$ claude mcp add sqlcl
--env TNS_ADMIN=/home/ubuntu/.oracle/wallets/dbdevel
-- /home/ubuntu/sqlcl/bin/sql -mcp
Added stdio MCP server sqlcl with command: /home/ubuntu/sqlcl/bin/sql -mcp to local config
File modified: /home/ubuntu/.claude.json [project: /home/ubuntu/claude]
ubuntu@server01:~/claude$ claude mcp list
claude.ai Google Drive: https://drivemcp.googleapis.com/mcp/v1 - ! Needs authentication
claude.ai Gmail: https://gmail.mcp.claude.com/mcp - ✓ Connected
claude.ai Google Calendar: https://gcal.mcp.claude.com/mcp - ! Needs authentication
sqlcl: /home/ubuntu/sqlcl/bin/sql -mcp - ✓ Connected
Lanzamos Claude Code y le pedimos que se conecte con el MCP usando el conector guardado. Cuando nos pida permiso para ejecutar herramientas, le decimos que no nos pida más permiso para esa acción — el MCP tiene un esquema de seguridad que podemos aprobar a nivel global una vez que lo utilizamos.
❯ conectate con el mcp a dbdevel_apptest ● Voy a cargar el esquema del tool de conexión SQL. Called sqlcl (ctrl+o to expand) ● Conectado exitosamente a dbdevel_apptest — Oracle Database 23.26.1.2.0. ¿Qué necesitas hacer?
Ahora a hacer magia directamente en la base. Le pedimos que nos cree un esquema con tablas y datos de prueba. Lo que me tomaría varias horas, Claude lo hace en minutos directamente en la base de datos.
❯ Puedes crear unas tablas de prueba en Oracle con relaciones entre ellas
de un sistema de ventas de paquetes turísticos. Simula unos 10 empleados
y unos 100 clientes. Solo mete datos de los últimos 3 meses. Los tours
que se venden son principalmente a Galápagos y son unos 10 tipos de tours.
Busca en internet si te falta información para generar datos ficticios.
● Voy a cargar los esquemas de ejecución SQL y construiré el sistema completo de tablas.
● Perfecto. Ejecuto en pasos — empiezo con el DDL, drop y creación de tablas.
Called sqlcl 2 times
● Tablas creadas. Inserto datos de referencia: destinos, tipos de tour, tours y empleados.
Called sqlcl
● Insertando 100 clientes... Called sqlcl 2 times
● Insertando 85 ventas... Called sqlcl 2 times
● Detalle de ventas y pagos... Called sqlcl 2 times
● Todo listo. Aquí el resumen:
Sistema de Ventas Turísticas Galápagos
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
8 tablas: DESTINOS → TOURS ← TIPOS_TOUR
EMPLEADOS ↘ ↙ CLIENTES
VENTAS
↓ ↓
DETALLE_VENTAS PAGOS
Tabla Registros
─────────────────────────────────────────────────────────────
DESTINOS 5 islas (Santa Cruz, San Cristóbal, Isabela...)
TIPOS_TOUR 7 (Crucero, Land-Based, Buceo, Fotografía...)
TOURS 10 paquetes — $1,200 a $4,500 por persona
EMPLEADOS 10 (1 Gerente + 9 Asesores, sueldos reales Ecuador)
CLIENTES 100 (50 ecuatorianos + 50 extranjeros, 15 países)
VENTAS 85 — ene 16 a abr 10, 2026
DETALLE_VENTAS 85 (tour + pasajeros por venta)
PAGOS 120 (completos, depósitos 50%, saldos, reembolsos)
─────────────────────────────────────────────────────────────
41 confirmadas · 25 completadas · 10 en proceso · 6 cotizaciones · 3 canceladas
Total facturado: $454,125
Realizamos una validación con el tools para ver que las tablas efectivamente tienen datos
