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

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):

Oracle Connection Variables

Tool Reference

86 tools across 15 categories.

Connection & SQL

Applications

Pages

Regions & Components

Items (Form Fields)

Buttons & Processes

Dynamic Actions

Charts & Visualizations

Shared Components

Schema Inspection

Generators (High-Level)

JavaScript

DevOps & Batch

Setup & Validation

Users

Code Examples

Example 1: Full app from schema (single command)

# Uses apex_generate_from_schema internally
# Prompt: "Generate a full app from tables EMPLOYEES, DEPARTMENTS, JOBS"
# Result: App with CRUD pages, dashboard, navigation — in ~10 seconds

Example 2: Incremental build

1. apex_connect()
2. apex_create_app(app_id=200, app_name="Inventory", home_page=1)
3. apex_add_page(page_id=1, page_name="Dashboard", page_mode="Normal")
4. apex_add_region(page_id=1, region_name="KPIs", region_type="STATIC")
5. apex_add_metric_cards(page_id=1, region_id=..., metrics=[...])
6. apex_generate_crud(table_name="PRODUCTS", start_page_id=10)
7. apex_add_nav_item("Dashboard", app_id=200, page_id=1, icon="fa-home")
8. apex_add_nav_item("Products", app_id=200, page_id=10, icon="fa-box")
9. apex_finalize_app()

Example 3: OpenAI Agents SDK

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    # apex-mcp must be running: apex-mcp --transport streamable-http
    async with MCPServerStreamableHttp(url="http://127.0.0.1:8000/mcp") as apex:
        agent = Agent(
            name="APEX Developer",
            instructions="Build Oracle APEX apps using apex-mcp tools.",
            mcp_servers=[apex],
        )
        result = await Runner.run(
            agent,
            "Connect to Oracle and generate a CRUD app for the ORDERS table."
        )
        print(result.final_output)

asyncio.run(main())

Example 4: Batch operations

apex_begin_batch()
# ... add many regions, items, processes ...
apex_commit_batch(rollback_on_error=True)
# All statements execute in one round-trip; rolls back on any error

Example 5: Dry-run mode

apex_dry_run_preview(enabled=True)
apex_generate_crud(table_name="EMPLOYEES")
# Logs all SQL without executing — useful for review before committing
apex_dry_run_preview(enabled=False)

Architecture

apex_mcp/
├── server.py          Entry point — FastMCP 3.x, argparse (stdio/http/sse)
├── __main__.py        Enables `python -m apex_mcp`
├── __init__.py        Version: 0.2.0
├── config.py          Constants (APEX version, workspace ID, date format)
├── db.py              ConnectionManager singleton — mTLS, retry, batch, dry-run
├── ids.py             Sequential ID generator (base 8_900_000_000_000_000)
├── session.py         ImportSession — tracks pages, regions, items, buttons
├── templates.py       Hardcoded Universal Theme 42 template IDs
├── validators.py      Input validation (page IDs, SQL, chart types, table names)
├── utils.py           Shared helpers (_esc, _blk, _sql_to_varchar2)
└── tools/
    ├── sql_tools.py       apex_connect, apex_run_sql, apex_status
    ├── app_tools.py       apex_create_app, apex_finalize_app, ...
    ├── page_tools.py      apex_add_page, apex_list_pages
    ├── component_tools.py apex_add_region, apex_add_item, apex_add_button, ...
    ├── shared_tools.py    apex_add_lov, apex_add_auth_scheme, ...
    ├── schema_tools.py    apex_list_tables, apex_describe_table, ...
    ├── generator_tools.py apex_generate_crud, apex_generate_dashboard, ...
    ├── js_tools.py        apex_add_page_js, apex_add_global_js, ...
    ├── inspect_tools.py   apex_get_app_details, apex_update_*, apex_delete_*, ...
    ├── user_tools.py      apex_create_user, apex_list_users
    ├── setup_tools.py     apex_setup_guide, apex_check_requirements, ...
    ├── validation_tools.py apex_add_item_validation, apex_add_item_computation
    ├── visual_tools.py    apex_add_jet_chart, apex_add_gauge, ...
    ├── advanced_tools.py  apex_generate_report_page, apex_generate_wizard, ...
    └── devops_tools.py    apex_generate_rest_endpoints, apex_export_page, ...

How APEX creation works

apex-mcp creates APEX applications by generating and executing wwv_flow_imp_page.*
PL/SQL calls directly against the Oracle database — the same mechanism used by APEX's
own import/export system. This bypasses the App Builder UI entirely and is fully
compatible with APEX 24.2.13 / Universal Theme 42.

HTTP transport note

When using --transport streamable-http or --transport sse, apex-mcp is a
single-user server: the ImportSession singleton means only one active import
session exists at a time. For multi-user scenarios, run separate server instances
on different ports.

Known Limitations

Requirements

No Oracle Instant Client required — the oracledb thin driver handles mTLS natively.

Troubleshooting

Connection issues

APEX issues

HTTP transport issues

Running Tests

cd apex-mcp
pip install -e ".[dev]"

# Unit tests (no database required)
pytest tests/ -v -m "not integration"

# All tests including integration (requires live Oracle connection)
pytest tests/ -v

The test suite has 51 unit tests covering tools, validators, and generators.

Demo Scripts

Run any demo (requires live Oracle connection):

python demos/build_app205.py

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new tools in tests/
4. Ensure pytest tests/ -m "not integration" passes
5. Submit a pull request

Adding a new tool

1. Add the function to the appropriate tools/*.py module
2. Register it in server.py with mcp.tool()(function_name)
3. Add unit tests in tests/
4. Update the Tool Reference section in this README

License

MIT — see LICENSE for details.

pt-BR: Este servidor MCP foi construído para o projeto Plataforma Desfecho TEA (Unimed Nacional),
usando Oracle APEX 24.2 + Oracle ADB 23ai. Para configuração detalhada do ambiente de produção,
consulte o CLAUDE.md na raiz do projeto.