Oci Db Management

An MCP (Model Context Protocol) server that wraps the OCI Database Management SDK, paired with a chain of Claude skills that turn natural language into guided Oracle database workflows.

You (natural language)
  → Claude
    → MCP Server (OCI DBM tools)
      → OCI Database Management APIs
        → Your Autonomous Database

---

What It Does

The onboarding skill chain takes a first-time user from zero to a fully enabled Oracle Autonomous Database — with OCI Database Management (DIAGNOSTICS_AND_MANAGEMENT) active — in a single guided conversation:

oci-setup              Validate OCI credentials, SDK, IAM, list compartments
  └─ oci-dbm-server    Start the MCP server (wires 24 DBM tools into Claude)
       └─ oci-dbm-commission   Orchestrator — grills the user, then runs:
            ├─ oci-dbm-network    Validate Private Endpoint + TCP 1522 rule
            ├─ oci-dbm-vault      Create vault secret + IAM policy (2 statements)
            ├─ oci-dbm-provision  Provision ADB (ECPU, TLS-only, private subnet)
            └─ oci-dbm-enable     Enable DIAGNOSTICS_AND_MANAGEMENT via feature API

Proof of full enablement: additional_details['databasePorts'] = '[ 1522 ]' on the managed database object. This field is empty after the legacy API. It is the canary.

---

Prerequisites

• Python 3.11+
• OCI Python SDK 2.100.0+ (pip install oci)
• ~/.oci/config with a valid [DEFAULT] profile
• OCI tenancy with:
  • A VCN with a private subnet
  • A DBM Private Endpoint (must be created via OCI Console — not available via SDK)
  • An OCI Vault with an encryption key

---

Installation

pip install oci-db-management-mcp-server

Or with uv:

uv tool install oci-db-management-mcp-server

Wire into Claude Desktop

Add to ~/.claude/claude_desktop_config.json (Mac/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "oci-db-management": {
      "command": "oci-db-management-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Restart Claude Desktop. The MCP server starts on demand.

---

Onboarding: From Zero to DBM-Enabled ADB

Step 1 — Validate credentials

"I have an Oracle Autonomous Database on OCI and I want Claude to manage it. How do I get started?"

Triggers oci-setup. Checks SDK version, config file, IAM connectivity, lists accessible compartments and any existing managed databases.

Step 2 — Start the server

"My OCI credentials are working. Now start the database management server."

Triggers oci-dbm-server. Starts the MCP server and confirms all 24 DBM tools are available.

Step 3 — Commission an ADB

"I want to create a new Autonomous Database and enable Database Management on it."

Triggers oci-dbm-commission. Before touching any API, it asks structured questions across four phases:

Phase 1 — Environment: Tenancy/compartment OCIDs, SDK version, vault availability.

Phase 2 — Network: VCN + private subnet, DBM Private Endpoint OCID, security list TCP ingress on port 1522 (not 1521 — ADB Shared uses TCPS on 1522).

Phase 3 — ADB spec: DB name, workload type, compute (ECPU — OCPU is deprecated), storage, TLS-only recommended with PE.

Phase 4 — DBM prerequisites: Vault secret for ADMIN password, IAM policy with two statements (one for the DBM service during enablement, one for the managed database principal for ongoing access).

After all phases pass a validation summary, the worker skills run in sequence with confirmation between each step.

---

Gotchas Surfaced by the Commission Flow

These are baked into the skill chain so users don't hit them:

1. Port 1522, not 1521 ADB Shared uses TCPS on port 1522. A missing ingress rule produces a generic JDBC timeout with no hint of the cause.

2. Two IAM policy statements required

Allow any-user to read secret-family in compartment 'X'
  where ALL {target.secret.id = '<ocid>',
             request.principal.type = 'dbmgmtmanageddatabase'}

Allow service dbmgmt to read secret-family in compartment 'X'
  where target.secret.id = '<ocid>'

Statement 1 covers ongoing DBM access after registration. Statement 2 covers the DBM service during the enablement call itself — when no managed database principal exists yet. Missing Statement 2 causes a silent auth failure.

3. Two DBM enable APIs — only one works

API	Result
DatabaseClient.enable_autonomous_database_management()	Sets status=ENABLED but no PE/credential connectivity. Jobs fail. Console shows green.
DbManagementClient.enable_autonomous_database_management_feature()	Full enablement. databasePorts=['1522'] confirms it.

The skill detects and clears the false-positive state before re-enabling correctly.

4. Full service name, not short name ep8c8t82piuc9mv_dbname_medium.adb.oraclecloud.com — from adb.connection_strings.medium. The short name silently fails.

5. ECPU, not OCPU OCPU compute model is deprecated for new ADB provisioning. The API accepts it but the resulting database may behave unexpectedly.

6. UpdatePolicyDetails must not include version_date Passing it (even as None) triggers a 400 from the IAM API.

---

MCP Server Tools (24 total)

list_managed_databases          get_fleet_summary
get_managed_database            list_compartments
list_db_management_private_endpoints

get_db_load                     get_top_wait_events
get_awr_report                  list_awr_snapshots

list_alert_logs                 get_parameter_changes
get_cursor_cache

start_sql_tuning_task           list_sql_tuning_advisor_tasks
list_sql_tuning_findings        list_sql_tuning_recommendations
get_sql_execution_plan

create_sql_job                  get_sql_job
list_sql_jobs                   list_job_executions
get_job_execution               list_job_execution_summaries

enable_database_management      get_work_request

Note: Diagnostic and operational tools (AWR, SQL Tuning, Jobs) require full DBM enablement (DIAGNOSTICS_AND_MANAGEMENT) on the target database. Monitoring-only enablement via the legacy API will not work.

---

Skills (Claude Code)

The skills in skills/ are Claude Code skills — they run inside Claude's agentic framework and invoke the MCP server tools. Copy them to your Claude skills directory or register them via the skills plugin.

Skill	Purpose
oci-setup	Entry point — validate SDK, config, IAM, list compartments
oci-dbm-server	Start the MCP server
oci-dbm-commission	Orchestrate full ADB onboarding
oci-dbm-network	Validate PE + security list
oci-dbm-vault	Create vault secret + IAM policy
oci-dbm-provision	Provision Autonomous Database
oci-dbm-enable	Enable DIAGNOSTICS_AND_MANAGEMENT

Coming in v1.1:

Skill	Purpose
oci-dbm-diagnose	Natural language DB diagnostics (AWR, wait events, load)
oci-dbm-performance	Fleet health overview
oci-dbm-jobs	Create and monitor DB Management jobs
oci-dbm-sql-tuning	SQL Tuning Advisor workflow

---

Architecture Notes

The MCP server uses STDIO transport (required for Claude Desktop integration). It initialises a single OCI config from ~/.oci/config [DEFAULT] at startup and reuses the connection across all tool calls.

Client routing:

• Alert logs → DiagnosabilityClient
• AWR, wait events, load, parameter changes, cursor cache → DbManagementClient
• SQL Tuning Advisor → SqlTuningClient
• Jobs → DbManagementClient
• ADB provisioning → DatabaseClient
• DBM feature enablement → DbManagementClient

---

Built With

• OCI Python SDK 2.173.0+
• Model Context Protocol (mcp Python package)
• Claude (Sonnet)

---

Contributing

Issues and PRs welcome. A contribution to oracle/mcp is planned once the feature tools reach v1.1.