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:

1. ORACLE_MCP_CONFIG environment variable
2. ./config/connections.json
3. ./connections.json
4. ~/.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