Oracle APEX MCP Server

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":["/ruta/a/oracle-apex-mcp-server/dist/index.js"],"env":{"TNS_ADMIN":"/ruta/a/network/admin"}}' --scope user

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

{
  "mcpServers": {
    "oracle-apex": {
      "type": "stdio",
      "command": "node",
      "args": ["/ruta/a/oracle-apex-mcp-server/dist/index.js"],
      "env": {
        "TNS_ADMIN": "/ruta/a/netwo