Oracle DB MCP Server

A Model Context Protocol (MCP) server for Oracle Database connectivity. This server enables AI tools like Cursor, Claude Desktop, and other MCP-compatible clients to interact with Oracle databases.

Features

Multiple Database Connections: Configure and manage multiple named Oracle database connections
Thin & Thick Mode Support: Works with Oracle's thin driver (no client required) or thick mode (with Oracle Instant Client)
Query Execution: Execute SELECT queries with result formatting
DML Operations: Execute INSERT, UPDATE, DELETE with safety checks
PL/SQL Support: Execute PL/SQL blocks, create procedures/functions
Schema Browsing: List tables, views, procedures, describe table structures
Stored Procedures: Execute stored procedures with input/output parameters
Transaction Management: Commit and rollback support
Safety Features: Read-only mode, dangerous query detection, automatic warnings

Installation

Using npx (Recommended)

No installation required. Configure your MCP client to run:

npx -y oracle-db-mcp

Local Installation

npm install -g oracle-db-mcp

Then run:

oracle-db-mcp

Configuration

Configuration File (connections.json)

Create a configuration file with your database connections:

{
  "oracleClient": {
    "mode": "thin"
  },
  "settings": {
    "defaultMaxRows": 100,
    "queryTimeout": 30
  },
  "connections": [
    {
      "name": "dev",
      "host": "dev-server.company.com",
      "port": 1521,
      "serviceName": "DEVDB",
      "username": "dev_user",
      "password": "dev_password",
      "mode": "readwrite"
    },
    {
      "name": "prod",
      "host": "prod-server.company.com",
      "port": 1521,
      "serviceName": "PRODDB",
      "username": "report_user",
      "passwordEnv": "PROD_DB_PASSWORD",
      "mode": "readonly"
    }
  ]
}

Connection Options

Each connection supports:

Option	Description
`name`	Unique identifier for the connection
`host`	Database server hostname
`port`	Port number (default: 1521)
`serviceName`	Oracle service name
`sid`	Oracle SID (alternative to serviceName)
`connectionString`	Full connection string (alternative to host/port/service)
`username`	Database username
`password`	Database password (direct)
`passwordEnv`	Environment variable containing password
`mode`	`readonly` or `readwrite`

Configuration File Locations

The server searches for configuration in this order:

ORACLE_MCP_CONFIG environment variable
./config/connections.json
./connections.json
~/.oracle-mcp/connections.json

Environment Variables

For simple single-connection setup:

export ORACLE_CONNECTION_NAME=mydb
export ORACLE_HOST=localhost
export ORACLE_PORT=1521
export ORACLE_SERVICE=XEPDB1
export ORACLE_USER=scott
export ORACLE_PASSWORD=tiger
export ORACLE_MODE=readonly

MCP Client Configuration

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["-y", "oracle-db-mcp"],
      "env": {
        "ORACLE_MCP_CONFIG": "/path/to/connections.json"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["-y", "oracle-db-mcp"],
      "env": {
        "ORACLE_MCP_CONFIG": "/path/to/connections.json"
      }
    }
  }
}

Available Tools

Connection Management

Tool	Description
`list_connections`	List all configured connections with status
`test_connection`	Test connectivity and get database info
`connect`	Establish a connection
`disconnect`	Close a connection

Query Execution

Tool	Description
`execute_query`	Execute SELECT queries
`execute_dml`	Execute INSERT/UPDATE/DELETE
`execute_plsql`	Execute PL/SQL blocks or DDL
`execute_procedure`	Call stored procedures

Schema Browsing

Tool	Description
`list_tables`	List tables and views
`describe_table`	Get column, constraint, index info
`list_procedures`	List procedures, functions, packages
`get_procedure_source`	Get source code of PL/SQL objects
`get_procedure_params`	Get procedure parameters
`explain_query`	Get query execution plan

Transaction Management

Tool	Description
`commit`	Commit current transaction
`rollback`	Rollback current transaction

Safety Features

Read-Only Mode

Connections configured as readonly:

Block all DML operations (INSERT, UPDATE, DELETE)
Block PL/SQL execution
Allow only SELECT queries

Dangerous Query Detection

The server warns or blocks:

DROP statements
TRUNCATE statements
UPDATE/DELETE without WHERE clause
ALTER SYSTEM commands

Oracle Client Modes

Thin Mode (Default)

No Oracle client installation required. Works with:

Oracle Database 12.1 and later
Oracle Cloud databases

Thick Mode

Requires Oracle Instant Client. Enable in config:

{
  "oracleClient": {
    "mode": "thick",
    "path": "/path/to/instantclient"
  }
}

Required for:

Oracle Database versions before 12.1
Advanced features (LDAP, Kerberos, etc.)
Some data types (BFILE, etc.)

Development

Building from Source

git clone https://github.com/titan213/oracle-db-mcp
cd oracle-db-mcp
npm install
npm run build

Running in Development

npm run dev

Testing

npm test

License

MIT

Author

Gihan Sundarapperuma gihan213@gmail.com