oraclemcp

Governed, least-privilege Oracle Database access for AI agents — in pure Rust.

oraclemcp is a Model Context Protocol server that gives an AI agent governed, least-privilege access to an Oracle database. Every raw statement the agent submits is classified before it can reach Oracle: read tools admit only statements *proven* read-only, and non-read SQL runs only through an explicit, profile-gated path that rolls DML back by default and requires a preview-derived grant before commit. Session elevation is explicit, temporary, and capped by profile max_level. The engine-free SQL guard remains independent of PL/SQL intelligence; the default binary embeds the offline engine. All crates use #![forbid(unsafe_code)].

_An independent open-source project — not affiliated with Oracle. See how it compares to Oracle's own MCP servers._

Drivers

The maintained primary driver is `oraclemcp-driver-cx`, oraclemcp's pure-Rust thin Oracle driver. The pinned official Oracle oracledb beta also ships as a bounded connect-time fallback for compatible password connections. No Oracle Instant Client, ODPI-C, or C toolchain is required.

flowchart LR

A["Connection request"] --> D["driver-cx pure-Rust · primary password · IAM · wallet · TCPS/PEM"] D -->|"basic-password connect fails"| O["oracledb Oracle · beta connect-time fallback"] D --> DB[("Oracle Database")] O --> DB

Only a failed basic-password connect ever falls back; IAM, wallet, and TCPS/PEM always stay on driver-cx, and a fallback never migrates a live session.

The official alternate emits TIMESTAMP WITH TIME ZONE values as UTC (Z). Driver-cx retains numeric offsets for supported values. The official adapter refuses TSTZ binds because it cannot preserve their supplied offset.

OCI Autonomous Database connectivity has an open post-ACCEPT authentication/TTC failure report (#54); this branch does not establish that a driver fix has resolved it. Token sources and wallet support do not prove ADB connectivity. Autonomous OCI token minting is also not implemented.

At a glance

Quick start

One line installs or updates on macOS and Linux (works pasted in a terminal or in a non-interactive agent run):

curl -fsSL "https://raw.githubusercontent.com/MuhDur/oraclemcp/main/install.sh?$(date +%s)" | bash

It verifies a SHA-256 digest (plus cosign signature/provenance when cosign is present) and installs oraclemcp and the short om alias into $HOME/.local. Also available: Windows (install.ps1), Docker (ghcr.io/muhdur/oraclemcp:latest), and cargo binstall oraclemcp. Air-gapped offline install, verification postures, and service install are documented via bash install.sh --help and docs/. No npm/npx channel is offered.

Onboard and connect a client:

oraclemcp setup --discover           # one READ_ONLY profile per tnsnames.ora entry — consent-gated, no secrets written to disk

oraclemcp doctor # offline diagnostics: driver, TNS/wallet, classifier, NLS oraclemcp serve --profile db_ro --allow-no-auth # stdio (local dev)

Wire it into an MCP client (e.g. Claude Desktop) over stdio:

{

"mcpServers": { "oracle": { "command": "oraclemcp", "args": ["serve", "--profile", "db_ro", "--allow-no-auth"] } } }

Several local MCP clients can use this same stdio configuration concurrently, including write-capable profiles. When service state is needed, clients automatically attach to one local broker that owns the audit writer and database pools. Each client retains its own session level, confirmation tokens, transaction and cancellation. The broker exits after 60 seconds without clients. HTTP also gives each client an isolated stateful session by default. HTTP and stdio clients share that same broker and state root. Each local client must resolve its own configured database credentials. Credentials that differ from the broker's receive ORACLEMCP_BROKER_CREDENTIAL_MISMATCH before opening a session.

Or run authenticated HTTP with a shown-once bearer, and open the local dashboard through a secret-free one-time pairing URL:

oraclemcp --json clients issue --label claude --scope oracle:read

oraclemcp serve --listen 127.0.0.1:7070 --client-credentials --profile db_ro om dashboard

doctor output is safe to paste into agent sessions — it omits connect strings, usernames, credential references, passwords, wallet paths, IAM tokens, and server DNs while keeping structured failure classes and ORA codes.

Why oraclemcp

• Fail-closed by construction. A SELECT an agent dreams up can never silently become a DELETE. Read tools admit only proven read-only SELECT/WITH and dictionary introspection. Non-read execution is isolated in oracle_execute, bounded by the profile ceiling, rollback-by-default for DML, and explicit-confirm-before-commit. *Forbidden* constructs (multi-statement batches, string-concat dynamic SQL, an unproven function call inside a SELECT) are rejected before touching Oracle, with a typed envelope and a suggested safe alternative.
• Agent-first UX. Every tool ships a real JSON Schema, title, and explicit MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Errors are structured ErrorEnvelopes with machine-stable classes, fuzzy suggestions, and next-step hints — never bare strings. A zero-arg oracle_capabilities tool lets an agent discover the surface.
• Pure Rust, no `unsafe`. Every crate is #![forbid(unsafe_code)]; the fail-closed classifier is a real sqlparser AST classifier and carries a differential cargo-fuzz target.
• Two transports. stdio (default) and Streamable HTTP (--listen) with fail-closed auth defaults, optional OAuth bearer enforcement, and native rustls TLS/mTLS.

How it compares

Oracle ships an official MCP built into SQLcl; ours is independent. On the axis that decides whether you can safely point an AI agent at a database — the guard between the agent and your data — here is the honest, evidence-backed contrast:

SQLcl-MCP rows reflect Oracle's own documentation (configure a minimum-privilege user, prefer a non-prod replica, audit via DBTOOLS$MCP_LOG); the oraclemcp rows are enforced in this repository. Oracle is the official, supported option, and its managed Autonomous MCP takes a different curated-report approach with per-user identity — strong for locked-down read-only BI.

Safety model

When a guarded request is refused, use the generated refusal catalogue for its typed safe next action; it never recommends bypassing the guard.

The core invariant is a fail-closed SQL guard — not "read-only forever." Operating levels form a ladder, READ_ONLY < READ_WRITE < DDL < ADMIN, surfaced through oracle_execute, oracle_compile_object, oracle_create_or_replace, oracle_patch_source, and oracle_set_session_level. Read-only is the default and the cap for unconfigured or protected profiles; a profile's max_level may permit escalation up to ADMIN. Every escalation is guarded:

• a preview → confirmation-token step-up before any non-read statement runs,
• a temporary, TTL-bounded elevation window,
• the classifier still gating every statement at the *current* level,
• DML rolling back by default, protected profiles pinned at READ_ONLY with an immutable ceiling, and OAuth scopes that can only *lower* the effective level,
• a signed, append-only, HMAC-SHA256 hash-chained audit record for every privileged action.

flowchart LR

A["Agent SQL"] --> C{"Fail-closed classifier"} C -->|"proven READ_ONLY"| R["Read tools · rows returned"] C -->|"forbidden / unparseable"| X["Refuse typed ErrorEnvelope"] C -->|"non-read"| L{"Operating-level gate READ_ONLY → READ_WRITE → DDL → ADMIN"} L -->|"above level / ceiling"| X L -->|"within profile ceiling"| P["Preview → confirmation token"] P --> E["Execute"] E -->|"DML"| RB["Rollback by default commit only with grant"] R --> AU[("Signed hash-chained audit")] E --> AU

An unparseable or unclassifiable statement fails closed. Statements can emit a verdict certificate bound to the classified bytes and the audit record; the routine-purity law it relies on is specified in proofs/purity-core/PurityCore.lean and pinned to the Rust classifier by a conformance test.

Governed dimensions

A database session is treated as a governed surface with several independent controls, each with an executable proof script:

| Egress | profile-scoped result masking applied before rows leave the server, with mask certificates (ADR 0008) | [served_egress.sh](scripts/e2e/served_egres