oraclemcp

[oraclemcp: governed, least-privilege Oracle Database MCP server in pure Rust]

[CI] [crates.io] [license] [forbid(unsafe_code)] [~3,300 tests] [nightly-2026-05-11]

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<br/>pure-Rust · primary<br/>password · IAM · wallet · TCPS/PEM"]    D -->|"basic-password<br/>connect fails"| O["oracledb<br/>Oracle · beta<br/>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 diskoraclemcp doctor                     # offline diagnostics: driver, TNS/wallet, classifier, NLSoraclemcp 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:readoraclemcp serve --listen 127.0.0.1:7070 --client-credentials --profile db_room 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<br/>classifier"}    C -->|"proven READ_ONLY"| R["Read tools · rows returned"]    C -->|"forbidden / unparseable"| X["Refuse<br/>typed ErrorEnvelope"]    C -->|"non-read"| L{"Operating-level gate<br/>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<br/>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:

What an agent sees depends on the active level and effective ceiling. At READ_ONLY, tools/list includes oracle_execute and execute_approved when the effective profile/OAuth ceiling permits READ_WRITE; their visibility grants no write authority. Other higher-level tools remain hidden until the session is elevated within the ceiling. A call to a not-yet-visible tool is refused with the same typed ErrorEnvelope as any other below-level statement.

Tools

The tables below are generated from the server's tool registry — the same descriptors tools/list serves — by scripts/docs_generate.sh (rendered from oraclemcp robot-docs tools --markdown). Do not hand-edit them; edit the registry and run bash scripts/docs_generate.sh --write.

Every advertised tool descriptor includes a human title plus explicit MCP annotations; these hints are advisory for clients, while the fail-closed classifier and operating-level gate remain the enforcement boundary. oracle_query and oracle_explain_plan also advertise outputSchema, and query results keep Oracle NUMBER cells as strings by default (opt into numbers_as_float=true explicitly). Beyond tools/*, initialize advertises resources, prompts, and completions (protocol 2025-11-25): resources/list exposes oracle://capabilities and oracle://tools, and read templates for oracle://schema/{owner} and oracle://object/{owner}/{type}/{name} route through the same safe dispatch path.

Compatibility aliases

For migrations from shorter Oracle MCP tool surfaces, the server advertises compatibility aliases that route to the guarded oracle_* tools and share their classifier, validation, and operating-level behavior. execute_approved, deploy_ddl, and read_patch_preview are wrappers rather than plain renames.

Deprecated argument aliases remain accepted until their removal version. Send only one spelling of each argument; canonical-plus-alias and two-alias requests are refused, even when values are equal. A lone alias emits _meta.deprecations.

Configuration

Connection profiles live in profiles.toml. No secrets are written to disk — credentials are references resolved at runtime through env:, file:, or keyring:. A minimal read-only profile:

[profiles.db_ro]connect_string = "//db.example.com:1521/FREEPDB1"username       = "APP_RO"credential_ref = "env:ORACLE_APP_PASSWORD"# default_level defaults to read_only and is the ceiling for this profile;# set max_level to permit explicit, TTL-bounded elevation up to ADMIN.

The full field reference — HTTP TLS/mTLS/OAuth listeners, the signed audit chain, result-masking policy, fleet/monitor profiles, TCPS/wallet and IAM/DRCP/proxy auth, and per-call timeout/SDU budgets — is in docs/configuration.md.

Documentation

• Installation manual — verified installers, air-gapped installs, updates, uninstall, services, dashboard pairing, and release channels.
• Configuration reference — every profile, auth, transport, audit, and masking field.
• Operating & deployment — containerized deployment, least-privilege account, network posture, service management (systemd/launchd/Windows), air-gapped install, and the operator runbook.
• TNS discovery onboarding · Toolchain · Upgrade runbooks and field-hardening notes.
• Architecture decisions: docs/adr/ · Formal proofs: proofs/purity-core/.

Build from source

This branch is pinned to nightly-2026-05-11 and has no stable MSRV (the pin arrives transitively through asupersync, and Windows needs windows_by_handle; see docs/toolchain.md). Prefer the verified release archive above; build from source only when you intend to:

rustup toolchain install nightly-2026-05-11 --component rustfmt --component clippycargo +nightly-2026-05-11 install oraclemcp

Live database access uses the maintained primary oraclemcp-driver-cx driver and requires no Oracle Instant Client, ODPI-C, or C toolchain. Set TNS_ADMIN for net-service-name connections when needed.

The release workflow builds every archive and the single ghcr.io/muhdur/oraclemcp image with the offline PL/SQL-intelligence engine included. The default source build includes it too; custom --no-default-features builds omit it. There is no separate engine image.

License

Licensed under Apache-2.0 OR MIT. The Docker image and crates do not redistribute Oracle Instant Client.