mcp-oracle-db

An MCP (Model Context Protocol) server for Oracle Database.

Lets AI assistants explore your database schema, run queries, write data, and monitor sessions — all through natural language.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

Features

• Explore — list schemas, tables, columns, indexes, constraints
• Query — execute SELECT with bind variables
• Write — INSERT, UPDATE, DELETE, MERGE, DDL (opt-in)
• Monitor — explain plans, active sessions, locks
• Safe — read-only by default, write requires explicit opt-in
• Zero install — Oracle Thin mode, no Oracle Client needed
• Connection pooling — efficient resource usage

Quick Start

npx mcp-oracle-db

Or install globally:

npm install -g mcp-oracle-db

Configuration

Set these environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | ORACLE_USER | Yes | — | Database username | | ORACLE_PASSWORD | Yes | — | Database password | | ORACLE_CONNECTION_STRING | Yes | — | host:port/service or TNS alias | | ORACLE_MODE | No | readonly | readonly or readwrite | | ORACLE_MAX_ROWS | No | 1000 | Max rows per query | | ORACLE_TNS_ADMIN | No | — | Path to tnsnames.ora directory | | ORACLE_WALLET_LOCATION | No | — | Path to Oracle Wallet (for cloud DBs) |

Connection string formats

# Standard
ORACLE_CONNECTION_STRING=myhost:1521/myservice

# TNS alias
ORACLE_CONNECTION_STRING=MY_TNS_ALIAS
ORACLE_TNS_ADMIN=/path/to/tns_admin

# Oracle Cloud / Autonomous DB (wallet)
ORACLE_CONNECTION_STRING=myatp_high
ORACLE_TNS_ADMIN=/path/to/wallet
ORACLE_WALLET_LOCATION=/path/to/wallet

Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "mcp-oracle-db"],
      "env": {
        "ORACLE_USER": "your_user",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_CONNECTION_STRING": "your_host:1521/your_service"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "mcp-oracle-db"],
      "env": {
        "ORACLE_USER": "your_user",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_CONNECTION_STRING": "your_host:1521/your_service"
      }
    }
  }
}

Cursor / Windsurf

Same format as Claude Code — add to your MCP settings with the env vars above.

Tools

Exploration

| Tool | Description | |---|---| | list_schemas | List all accessible schemas | | list_tables | List tables and views in a schema | | describe_table | Columns, PKs, FKs, indexes of a table |

Query

| Tool | Description | |---|---| | query | Run SELECT queries (supports bind variables) |

Write (requires ORACLE_MODE=readwrite)

| Tool | Description | |---|---| | execute | Run DML — INSERT, UPDATE, DELETE, MERGE | | ddl | Run DDL — CREATE, ALTER, DROP, TRUNCATE |

DBA / Monitoring

| Tool | Description | |---|---| | explain_plan | Execution plan for a query | | session_info | Current session details | | active_sessions | All active database sessions | | locks | Active locks and blockers |

Security

• Read-only by default — writes blocked unless ORACLE_MODE=readwrite
• SQL validation — query only accepts SELECT/WITH
• Bind variables — prevents SQL injection
• No credentials in code — everything via environment variables

Requirements

• Node.js >= 18
• Oracle Database (any version)
• No Oracle Client installation needed

License

MIT