apex-mcp — Oracle APEX MCP Server

Build, inspect, and modify Oracle APEX 24.2 applications via natural language. Works with Claude, GPT, Gemini, Cursor, VS Code, and any MCP-compatible AI client.

Overview

apex-mcp is a Model Context Protocol (MCP) server that exposes 86 tools for building Oracle APEX 24.2 applications through AI assistants. Built on FastMCP 3.x and Python 3.11+, it connects to Oracle Autonomous Database via the oracledb thin driver (mTLS wallet — no Oracle Instant Client required).

Instead of navigating the APEX App Builder UI, you describe what you want and the AI does the work: create apps, generate CRUD pages, add JET charts, configure auth schemes, export pages, generate REST endpoints, and more.

┌─────────────────────────────────────────────────────────────────┐
│  AI Client (Claude / GPT / Gemini / Cursor / VS Code)           │
│                                                                  │
│  "Create a full HR app from the EMPLOYEES table"                 │
└────────────────────────────┬────────────────────────────────────┘
                             │ MCP (stdio or HTTP)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  apex-mcp server (FastMCP 3.x, Python 3.11+)                    │
│  86 tools across 15 categories                                   │
└────────────────────────────┬────────────────────────────────────┘
                             │ oracledb (mTLS)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│  Oracle Autonomous Database 23ai                                 │
│  wwv_flow_imp_page → APEX 24.2 App Builder                      │
└─────────────────────────────────────────────────────────────────┘

Supported AI Clients

| Client | Transport | Config File | Setup Guide | |--------|-----------|-------------|-------------| | Claude Code | stdio | .mcp.json | docs/setup-claude.md | | Claude Desktop | stdio | claude_desktop_config.json | docs/setup-claude.md | | GPT / OpenAI Agents SDK | streamable-http | Python code | docs/setup-gpt.md | | Google Gemini CLI | stdio | .gemini/settings.json | docs/setup-gemini.md | | Cursor IDE | stdio | .cursor/mcp.json | docs/setup-cursor.md | | VS Code / GitHub Copilot | stdio or http | .vscode/mcp.json | docs/setup-vscode.md | | ZAI (visual companion) | n/a | side-by-side | docs/setup-zai.md |

Quick Start

1. Install

git clone https://github.com/your-org/apex-mcp
cd apex-mcp
pip install -e .

2. Configure

Copy and edit the config file for your AI client:

Claude Code — create .mcp.json in your project root:

{
  "mcpServers": {
    "apex-mcp": {
      "command": "python",
      "args": ["-m", "apex_mcp"],
      "cwd": "/path/to/apex-mcp",
      "env": {
        "ORACLE_DB_USER": "YOUR_SCHEMA",
        "ORACLE_DB_PASS": "YOUR_PASSWORD",
        "ORACLE_DSN": "YOUR_DSN",
        "ORACLE_WALLET_DIR": "/path/to/wallet",
        "ORACLE_WALLET_PASSWORD": "YOUR_WALLET_PW",
        "APEX_WORKSPACE_ID": "YOUR_WORKSPACE_ID",
        "APEX_SCHEMA": "YOUR_SCHEMA",
        "APEX_WORKSPACE_NAME": "YOUR_WORKSPACE"
      }
    }
  }
}

For other clients see Supported AI Clients above.

3. Verify

In Claude Code:

/mcp

You should see apex-mcp connected with 86 tools.

Then:

Connect to Oracle and list all APEX applications in the workspace.

Transport Modes

apex-mcp supports three transport modes, controlled via --transport flag or environment variables.

stdio (default — local clients)

python -m apex_mcp                        # default
python -m apex_mcp --transport stdio      # explicit
apex-mcp                                  # if installed via pip

Best for: Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI.

Streamable HTTP (remote / multi-client)

apex-mcp --transport streamable-http --port 8000
# Server available at: http://127.0.0.1:8000/mcp

Best for: OpenAI Agents SDK, Codespaces, remote setups, multiple clients.

SSE (Server-Sent Events)

apex-mcp --transport sse --port 9000
# Server available at: http://127.0.0.1:9000/sse

Best for: clients that specifically require SSE transport.

Environment Variables

All CLI flags have environment variable equivalents (lower priority than CLI args):

| Variable | CLI flag | Default | |----------|----------|---------| | MCP_TRANSPORT | --transport | stdio | | MCP_HOST | --host | 127.0.0.1 | | MCP_PORT | --port | 8000 | | MCP_PATH | --path | /mcp (http) or /sse |

Oracle Connection Variables

| Variable | Description | |----------|-------------| | ORACLE_DB_USER | Oracle schema name | | ORACLE_DB_PASS | Oracle schema password | | ORACLE_DSN | TNS alias or connect string | | ORACLE_WALLET_DIR | Directory containing wallet files (cwallet.sso, etc.) | | ORACLE_WALLET_PASSWORD | Wallet encryption password | | APEX_WORKSPACE_ID | Numeric APEX workspace ID | | APEX_SCHEMA | Schema that owns APEX objects | | APEX_WORKSPACE_NAME | APEX workspace name |

Tool Reference

86 tools across 15 categories.

Connection & SQL

| Tool | Description | |------|-------------| | apex_connect | Connect to Oracle ADB (mTLS wallet) | | apex_run_sql | Execute any SELECT/DML/DDL statement | | apex_status | Show connection status and session info |

Applications

| Tool | Description | |------|-------------| | apex_create_app | Create a new APEX application (starts import session) | | apex_finalize_app | Finalize and commit the application | | apex_list_apps | List all apps in the workspace | | apex_delete_app | Delete an application | | apex_get_app_details | Get full app configuration | | apex_validate_app | Validate app structure (home page, orphan items, etc.) | | apex_dry_run_preview | Toggle dry-run mode (log SQL without executing) | | apex_describe_page | Describe a page's components in human-readable form |

Pages

| Tool | Description | |------|-------------| | apex_add_page | Add a new page to the app | | apex_list_pages | List all pages | | apex_get_page_details | Get full page details | | apex_update_page | Update page properties | | apex_delete_page | Delete a page | | apex_copy_page | Copy a page to a new ID | | apex_diff_app | Compare app structure before/after changes |

Regions & Components

| Tool | Description | |------|-------------| | apex_add_region | Add a region (HTML, IR, report, etc.) | | apex_list_regions | List regions on a page | | apex_update_region | Update region properties | | apex_delete_region | Delete a region | | apex_add_interactive_grid | Add an Interactive Grid region | | apex_add_master_detail | Add a master-detail region pair | | apex_add_notification_region | Add a notification/alert region | | apex_add_timeline | Add a timeline region | | apex_add_breadcrumb | Add a breadcrumb navigation region | | apex_add_faceted_search | Add a faceted search region | | apex_add_file_upload | Add a file upload component | | apex_add_search_bar | Add a search bar component |

Items (Form Fields)

| Tool | Description | |------|-------------| | apex_add_item | Add a form item (text, select, date, etc.) | | apex_list_items | List items on a page | | apex_update_item | Update item properties | | apex_delete_item | Delete an item | | apex_bulk_add_items | Add multiple items in one call | | apex_add_item_validation | Add server-side validation to an item | | apex_add_item_computation | Add a computation to set item value |

Buttons & Processes

| Tool | Description | |------|-------------| | apex_add_button | Add a button to a page/region | | apex_delete_button | Delete a button | | apex_add_process | Add a page process (PL/SQL, DML, branch) | | apex_list_processes | List page processes |

Dynamic Actions

| Tool | Description | |------|-------------| | apex_add_dynamic_action | Add a dynamic action (client-side event handler) | | apex_list_dynamic_actions | List dynamic actions on a page |

Charts & Visualizations

| Tool | Description | |------|-------------| | apex_add_jet_chart | Add an Oracle JET chart (bar, line, pie, etc.) | | apex_add_gauge | Add a gauge/dial chart | | apex_add_funnel | Add a funnel chart | | apex_add_sparkline | Add a sparkline chart | | apex_add_metric_cards | Add metric/KPI cards with gradient styling | | apex_add_calendar | Add a calendar region | | apex_add_chart_drilldown | Add drill-down behavior to a chart |

Shared Components

| Tool | Description | |------|-------------| | apex_add_lov | Add a List of Values (static or dynamic) | | apex_list_lovs | List all LOVs in the app | | apex_add_auth_scheme | Add an authorization scheme | | apex_list_auth_schemes | List authorization schemes | | apex_add_nav_item | Add a navigation menu item | | apex_add_app_item | Add an application-level item (global variable) | | apex_add_app_process | Add an application-level process |

Schema Inspection

| Tool | Description | |------|-------------| | apex_list_tables | List Oracle tables/views in the schema | | apex_describe_table | Descri

Apex MCP

Install / Use

README