MCP-Oracle

Español | Inglés

Servidor MCP (Model Context Protocol) que conecta un agente de IA a una base de datos Oracle.

Expone herramientas para explorar el esquema, leer el código fuente de PL/SQL y ejecutar SQL. Se inicia en modo solo lectura; las escrituras y las llamadas a procedimientos almacenados se habilitan con ORACLE_ALLOW_WRITE=true.

Utiliza el SDK oficial de Python (mcp) y python-oracledb. Si encuentra un Instant Client (o el directorio lib/ de un ORACLE_HOME), habilita el modo thick; de lo contrario, usa el modo thin. El modo thick es necesario para instancias antiguas (10g/11g) cuyo verificador de contraseña no es compatible con el modo thin.

Este proyecto no es el conjunto oficial de MCP de Oracle (oracle/mcp). Ese repositorio está dirigido a Oracle Cloud y otros productos de Oracle. Este servidor se comunica directamente con el listener de tu base de datos.

Herramientas

run_query y execute_dml aceptan variables de enlace (:name) para que no concatenes valores en el SQL.

Related MCP server: Oracle DB MCP Server

Requisitos

• Python 3.9+

• Acceso a una instancia de Oracle (usuario, contraseña, host, puerto y service_name)

• Para Oracle 10g/11g (o cuando el modo thin falla): Oracle Instant Client o el directorio lib/ de un ORACLE_HOME

Uso local vs producción

Este README cubre el uso local: Cursor o Claude Desktop inician server.py en tu máquina a través de stdio (no abre un puerto HTTP).

Si el MCP debe seguir ejecutándose en un servidor y los clientes se conectan a través de la red:

• Linux (RedHat)

• Windows Server

Instalación

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Copia la plantilla de entorno y completa tus valores:

cp .env.example .env

El servidor no carga .env automáticamente. Esas variables deben pasarse en la configuración del cliente MCP (Cursor, Claude Desktop, etc.). El archivo .env es una referencia local; no lo confirmes en el repositorio.

Variables de entorno

Modo thick vs thin

Al iniciar, el servidor comprueba ORACLE_CLIENT_LIB_DIR (o ~/oracle/instantclient). Si esa carpeta existe, llama a oracledb.init_oracle_client() y usa el modo thick.

Ejemplos:

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

Si no hay un cliente nativo, se ejecuta en modo thin (Oracle 12.1+ en la mayoría de los casos).

Uso con Cursor

En Cursor, añade el servidor a la configuración de MCP (por ejemplo ~/.cursor/mcp.json o la configuración del proyecto):

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Usa la ruta absoluta al Python de .venv para que el cliente encuentre mcp y oracledb.

Reinicia Cursor (o recarga los servidores MCP) y confirma que oracle-mcp aparece en la lista de herramientas.

Uso con Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Ejecución manual

Localmente, el servidor habla MCP a través de stdio (no abre un puerto HTTP). En un servidor de producción, el transporte es HTTP; consulta Uso local vs producción.

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

Sin un cliente MCP conectado a stdin/stdout no verás un prompt interactivo; eso es lo esperado.

Seguridad

• Por defecto ORACLE_ALLOW_WRITE=false: execute_dml y call_procedure fallan con PermissionError.

• run_query rechaza sentencias que comiencen con INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, TRUNCATE, CREATE, GRANT o REVOKE.

• execute_dml solo acepta INSERT, UPDATE, DELETE o MERGE.

• Prefiere variables de enlace (:id) en lugar de interpolar valores en el SQL.

• Conéctate con un usuario de privilegios mínimos cuando solo necesites explorar el esquema.

• No confirmes .env ni credenciales en un mcp.json versionado.

Dependencias

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0