homemade-mcp-oracle-database-10g-claude

Utilidad de solo lectura para consultar una base de datos Oracle Database 10g desde un servidor MCP y/o directamente desde la terminal via una skill de Claude Code. Ver el requerimiento original en requeriments.txt.

Por que existe esto

Oracle 10g quedo fuera de soporte extendido hace mas de una decada. Los drivers modernos de Oracle (python-oracledb, node-oracledb) usan por defecto un modo "thin" que solo habla el protocolo de red de Oracle 12c en adelante. Para hablar con un 10g hace falta forzar el modo "thick", apoyandose en un Oracle Instant Client instalado localmente. La mayoria de los MCP de Oracle genericos no exponen esa opcion, de ahi esta utilidad a medida.

Confirmado en este proyecto: un Oracle Instant Client 19.x en modo thick si logra conectar contra un Oracle Database 10g Release 10.2.0.3.0 (no hizo falta bajar a Instant Client 11.2 como se anticipaba).

Related MCP server: MCP Oracle Server

Arquitectura

src/
  config.py           Carga y valida .env (conexion, Instant Client, politica)
  db.py                Conexion Oracle en modo thick (oracledb.init_oracle_client)
  sql_guard.py         Guard de solo-lectura: solo permite SELECT / WITH
  audit_log.py         Logging de auditoria (logs/query_audit.log)
  query_runner.py      Ejecuta SQL con limite de filas (MAX_ROWS), timeout y auditoria
  schema_inspector.py  Consultas de catalogo (list_tables / describe_table), SQL 10g-safe
  mcp_server.py        Servidor MCP (tools: run_query_tool, list_tables, describe_table)

scripts/
  install.py           Instalador automatico (venv, deps, .env, mcp-config.json, registro en Claude Code)
  test_connection.py   Prueba minima de conectividad (Fase 0)
  query.py             CLI de consultas (Fase 1) usado tambien por la skill

install.sh / install.bat   Wrappers de un solo paso que llaman a scripts/install.py

.claude/skills/oracle10g-query/SKILL.md   Skill de Claude Code (usa scripts/query.py)

Tanto el CLI como el servidor MCP reutilizan el mismo nucleo (config -> db -> sql_guard/query_runner), asi que la politica de seguridad y los limites se aplican una sola vez, en un solo lugar.

Modelo de seguridad (defensa en profundidad)

1. A nivel de base de datos: el usuario Oracle configurado ya tiene permisos de solo lectura otorgados por el DBA. Esta es la barrera principal y real.

2. A nivel de software (src/sql_guard.py): antes de mandar cualquier SQL "libre" (el que llega por run_query/run_query_tool) se valida que sea una unica sentencia SELECT o WITH ... SELECT. Se rechaza cualquier INSERT/UPDATE/DELETE/MERGE, DDL, GRANT/REVOKE, PL/SQL (BEGIN, EXEC, ...) o sentencias apiladas con ;. Las consultas de catalogo (list_tables/describe_table) no pasan por este guard porque su SQL es fijo y escrito por esta misma utilidad; solo sus parametros (schema/table_name) van como bind variables.

3. Limites de ejecucion: MAX_ROWS limita filas devueltas (via fetchmany, el resultado indica truncated: true si aplico) y QUERY_TIMEOUT_SECONDS corta la consulta si se cuelga (cursor.callTimeout).

4. Auditoria: toda ejecucion (exitosa, con error de Oracle, o rechazada por el guard) queda registrada en logs/query_audit.log con usuario, SQL y resultado.

Instalacion

Automatica (recomendado)

Justo despues de clonar el repo, corre el instalador para tu sistema:

# Linux/macOS
./install.sh

# Windows
install.bat

(equivalente en cualquier SO: python scripts/install.py)

Esto hace todo el setup sin pasos manuales:

1. Crea el entorno virtual en .venv (si no existe).

2. Instala las dependencias de requirements.txt dentro de ese venv.

3. Copia .env.example a .env si .env todavia no existe (las credenciales reales las tenes que llenar vos a mano, eso nunca se automatiza).

4. Genera mcp-config.json (gitignored) con las rutas absolutas ya resueltas para esta maquina — al python del venv y a src/mcp_server.py — listo para pegar en la config de un cliente MCP como Claude Desktop.

5. Si el CLI claude esta instalado, registra el servidor MCP automaticamente con claude mcp add (scope user), sin que tengas que armar el comando a mano.

Es seguro volver a correrlo: no pisa un .env existente ni duplica el registro en Claude Code, salvo que le pases --force. Usa --no-register si no queres tocar la config de Claude Code.

Al final falta solo un paso manual, imposible de automatizar: editar .env con tus datos reales (ver comentarios en .env.example): host/puerto/ service_name o SID, usuario y password del usuario de solo lectura, y la ruta de tu Oracle Instant Client (ORACLE_INSTANT_CLIENT_DIR). Nunca subas .env a un repositorio.

Manual

Si preferis armar el entorno vos mismo en vez de usar el instalador:

python -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
copy .env.example .env

(en Linux/macOS: .venv/bin/python -m pip install -r requirements.txt y cp .env.example .env)

Edita .env con tus datos reales igual que en la instalacion automatica.

Uso

1. Probar conectividad

.venv\Scripts\python scripts\test_connection.py

2. CLI de consultas

.venv\Scripts\python scripts\query.py "SELECT * FROM alguna_tabla WHERE ROWNUM <= 10" --format json
.venv\Scripts\python scripts\query.py --file consulta.sql --format table

3. Servidor MCP

Correrlo manualmente (stdio), invocando el archivo directamente (no con -m, ver nota abajo):

.venv\Scripts\python src\mcp_server.py

Si corriste el instalador automatico, esto ya esta hecho: el registro en Claude Code se hizo solo, y el archivo mcp-config.json (gitignored) ya tiene las rutas de tu maquina resueltas para pegarlo en otro cliente MCP (Claude Desktop, etc.).

Para registrarlo a mano en Claude Code:

claude mcp add oracle10g -s user -- "<ruta>\.venv\Scripts\python.exe" "<ruta>\src\mcp_server.py"

o para otro cliente MCP, ver mcp-config.example.json como plantilla — ajusta las rutas a tu maquina y agrega ese bloque a la config de mcpServers del cliente (o copia directo el mcp-config.json que genera el instalador).

Nota: el comando usa la ruta absoluta a src\mcp_server.py en vez de python -m src.mcp_server. Un cliente MCP lanza este proceso con un cwd que no controlas (y el formato estandar de mcpServers no soporta una clave cwd), asi que -m src.mcp_server puede fallar con ModuleNotFoundError: No module named 'src' si ese cwd no es la raiz del repo. mcp_server.py se agrega a si mismo al sys.path usando su propia ubicacion (__file__, siempre absoluta) antes de importar el resto del paquete, igual que hacen scripts/*.py, para no depender del cwd.

Tools expuestos:

• run_query_tool(sql) — ejecuta un SELECT (guard de solo-lectura aplica).

• list_tables(schema?) — lista tablas del catalogo (all_tables).

• describe_table(table_name, schema?) — columnas de una tabla (all_tab_columns).

4. Skill de Claude Code

Ver .claude/skills/oracle10g-query/SKILL.md. Se activa cuando le pides a Claude Code consultar o verificar datos de esta base; internamente usa el mismo scripts/query.py.

Particularidad de Oracle 10g a tener en cuenta

Oracle 10g no soporta FETCH FIRST n ROWS ONLY / OFFSET (sintaxis 12c+). Para limitar filas en una consulta usa ROWNUM:

SELECT * FROM (
  SELECT col1, col2 FROM tabla ORDER BY col1
) WHERE ROWNUM <= 20