MCP-Oracle

Español | English

MCP (Model Context Protocol) server that connects an AI agent to an Oracle database.

It exposes tools to explore the schema, read PL/SQL source, and run SQL. It starts in read-only mode; writes and stored-procedure calls are enabled with ORACLE_ALLOW_WRITE=true.

It uses the official Python SDK (mcp) and python-oracledb. If it finds an Instant Client (or the lib/ directory of an ORACLE_HOME), it enables thick mode; otherwise it uses thin mode. Thick mode is required for older instances (10g/11g) whose password verifier is not supported in thin mode.

This project is not the official Oracle MCP suite (oracle/mcp). That repository targets Oracle Cloud and other Oracle products. This server talks directly to your database listener.

Tools

run_query and execute_dml accept bind variables (:name) so you do not concatenate values into SQL.

Related MCP server: Oracle DB MCP Server

Requirements

• Python 3.9+

• Access to an Oracle instance (user, password, host, port, and service_name)

• For Oracle 10g/11g (or when thin mode fails): Oracle Instant Client or the lib/ directory of an ORACLE_HOME

Local use vs production

This README covers local use: Cursor or Claude Desktop start server.py on your machine over stdio (it does not open an HTTP port).

If the MCP should keep running on a server and clients connect over the network:

• Linux (RedHat)

• Windows Server

Installation

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

Copy the environment template and fill in your values:

cp .env.example .env

The server does not load .env automatically. Those variables must be passed in the MCP client configuration (Cursor, Claude Desktop, and so on). The .env file is a local reference; do not commit it.

Environment variables

Thick vs thin mode

On startup the server checks ORACLE_CLIENT_LIB_DIR (or ~/oracle/instantclient). If that folder exists, it calls oracledb.init_oracle_client() and uses thick mode.

Examples:

# 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

If there is no native client, it runs in thin mode (Oracle 12.1+ in most cases).

Using with Cursor

In Cursor, add the server to the MCP configuration (for example ~/.cursor/mcp.json or the project configuration):

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

Use the absolute path to the .venv Python so the client finds mcp and oracledb.

Restart Cursor (or reload MCP servers) and confirm that oracle-mcp appears in the tools list.

Using with Claude Desktop

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

Running by hand

Locally the server speaks MCP over stdio (it does not open an HTTP port). On a production server the transport is HTTP; see Local use vs production.

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

Without an MCP client attached to stdin/stdout you will not see an interactive prompt; that is expected.

Security

• By default ORACLE_ALLOW_WRITE=false: execute_dml and call_procedure fail with PermissionError.

• run_query rejects statements that start with INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, TRUNCATE, CREATE, GRANT, or REVOKE.

• execute_dml only accepts INSERT, UPDATE, DELETE, or MERGE.

• Prefer bind variables (:id) instead of interpolating values into SQL.

• Connect with a least-privilege user when you only need to explore the schema.

• Do not commit .env or credentials in a versioned mcp.json.

Dependencies

• mcp ≥ 1.2.0

• oracledb ≥ 2.4.0