Oracle APEX MCP Server

MCP (Model Context Protocol) server for Oracle Database and Oracle APEX integration. Provides 25 tools for multi-database management, querying, executing DDL/DML, inspecting database objects, and reading APEX metadata — all through a standardized MCP interface.

Features

• Multi-database support: switch between databases on the fly without restarting
• TNS names: auto-discovers tnsnames.ora from ORACLE_HOME, TNS_ADMIN, or common paths
• 3 connection modes: TNS alias, connection string, or manual (host/port/service)
• Oracle Database: query, execute DML/DDL/PL/SQL, transactions, explain plans, compile objects, show errors
• Object Inspection: list tables, describe tables (columns, indexes, constraints, triggers), list objects, get source, search, dependencies
• APEX Metadata (read-only): list applications, describe apps/pages, workspace users, REST services, ORDS-enabled objects
• Connection pooling with configurable min/max/timeout
• Thick mode support for legacy Oracle databases (pre-12c crypto)

Requirements

• Node.js >= 18.0.0
• Oracle Database accessible via network (any version supported by oracledb driver)
• Oracle Instant Client (only if using Thick mode for legacy databases)

Quick Install (auto-registers with Claude Code)

git clone <repo-url>
cd oracle-apex-mcp-server
npm install
npm run install:claude

That's it. Restart Claude Code and start using it. No manual configuration needed.

The installer will:

1. Install dependencies
2. Build the TypeScript project
3. Register the MCP server in ~/.claude/mcp.json

To register for a specific project instead: npm run install:project

Windows note: If npm run build runs out of memory, use:

set NODE_OPTIONS=--max-old-space-size=4096
npx tsc

How It Works

When you start a Claude Code session, the server starts with no pre-configured database. You choose how to connect:

1. Browse available databases from TNS

> list my available oracle databases
  (Claude calls oracle_list_tns_entries)

> connect to PROD_DB as user hr
  (Claude calls oracle_connect mode=tns tns_alias=PROD_DB username=hr password=...)

2. Connect with host/port/service

> connect to oracle on 192.168.1.100 port 1521 service MYDB as user admin
  (Claude calls oracle_connect mode=manual host=192.168.1.100 port=1521 service_name=MYDB ...)

3. Switch databases anytime

> switch to DEV_DB
  (Claude calls oracle_connect mode=tns tns_alias=DEV_DB ...)

> now switch to TEST_DB
  (same — closes old pool, opens new one)

4. Check current connection

> which database am I connected to?
  (Claude calls oracle_current_connection)

Configuration

Environment Variables (all optional)

Set these in ~/.claude/mcp.json under env if you want a default connection at startup:

TNS Discovery

The server automatically searches for tnsnames.ora in these locations (in order):

1. $TNS_ADMIN/tnsnames.ora
2. $ORACLE_HOME/network/admin/tnsnames.ora
3. Common Windows paths (C:\oracle\..., C:\app\oracle\...)
4. Common Linux paths (/etc/oracle/..., /opt/oracle/..., /u01/...)

Manual Claude Code Setup

If you prefer manual configuration instead of the auto-installer:

Option 1: CLI command

claude mcp add-json oracle-apex '{"type":"stdio","command":"node","args":["C:/Users/sotelos/oracle-apex-mcp-server/dist/index.js"],"env":{"TNS_ADMIN":"C:/oracle/network/admin"}}' --scope user

Option 2: Edit ~/.claude/mcp.json

{
  "mcpServers": {
    "oracle-apex": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/sotelos/oracle-apex-mcp-server/dist/index.js"],
      "env": {
        "TNS_ADMIN": "C:/oracle/network/admin",
        "ORACLE_OLD_CRYPTO": "true",
        "ORACLE_CLIENT_LIB_DIR": "C:/oracle/instantclient_19_26"
      }
    }
  }
}

With default connection at startup

{
  "mcpServers": {
    "oracle-apex": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/sotelos/oracle-apex-mcp-server/dist/index.js"],
      "env": {
        "ORACLE_HOST": "myhost",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "MYDB",
        "ORACLE_USERNAME": "myuser",
        "ORACLE_PASSWORD": "mypassword"
      }
    }
  }
}

Available Tools (25)

Connection Management (4) — NEW

Database Tools (9)

Object Inspection Tools (6)

APEX Metadata Tools (6) — Read-Only

Development

npm run build            # Compile TypeScript
npm run start            # Run the compiled server
npm run dev              # Build + start
npm run install:claude   # Build + register in ~/.claude/mcp.json
npm run install:project  # Build + register in .claude/mcp.json (current dir)
npm run clean            # Remove dist/

License

MIT