Oraclemcp

Install, service, dashboard

One line installs or updates oraclemcp on macOS and Linux. It works as pasted for a human terminal and for a non-interactive agent run:

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

The hosted script fetch includes a cache buster so stale CDN/proxy copies do not hide installer updates. This command is literal and copy-pasteable for release 0.8.0; change only the version number when installing another release. Later examples that contain ..., `, `, or placeholder env values are templates: replace those placeholders before running them.

The normal command downloads, verifies, and installs into $HOME/.local unless you pass --prefix. It requires the SHA-256 digest check, verifies the cosign blob signature and provenance attestation when cosign is installed, and installs oraclemcp plus the short om alias. Missing cosign is a visible authenticity-unverified posture by default; use --verify require when your environment requires cosign to be present.

In an interactive terminal, the installer then offers a short guided flow: append the binary directory to PATH, run doctor, offer zero-config database discovery from tnsnames.ora, print an MCP client snippet, and optionally install the loopback service. In a pipe, CI job, or agent run, it never prompts, never scans, and never starts a service; it installs the binary and prints the exact PATH line plus next steps on stderr. Every install finishes with next steps on stderr: discover databases, run doctor, write the starter profile, and generate MCP client snippets.

Get started in minutes: zero-config onboarding

oraclemcp setup --discover finds every database defined in your tnsnames.ora and writes one read-only connection profile per net-service — through the same governed config-ops path (timestamped backup, atomic write, strict re-validation) used everywhere else. It is consent-gated: an interactive run asks before it scans and again before it writes; a non-interactive run without --discover-tns (or --yes) refuses with exit code 2 and scans nothing. It writes no secrets to disk — each profile references an environment variable (env:ORACLE__PASSWORD) you export yourself — keeps every profile capped at READ_ONLY, and is idempotent and non-destructive: existing profiles and hand edits are preserved, only new databases are added. When no tnsnames.ora is found it falls back to the minimal starter profile so you still boot. Add --json for a names-only agent report, or --dry-run to preview without writing. Run oraclemcp doctor afterwards to see exactly which credentials remain to be set. Full contract: docs/tns-discovery-onboarding.md.

Re-running the same one-liner is the update path. Re-running the same verified archive is a no-op for identical installed files; re-running with a newer target updates atomically after backing up the previous binary. A downgrade is refused unless you pass --force.

Release 0.8.0 operator notes: [docs/upgrading-to-0.8.0.md](docs/upgrading-to-0.8.0.md), [docs/downgrading-0.8.0-to-0.7.2.md](docs/downgrading-0.8.0-to-0.7.2.md), and [docs/feature-rollout-0.8.0.md](docs/feature-rollout-0.8.0.md).

Use the dry-run command first when you want a preview: it prints the archive, verification inputs, files, service plan, client-registration plan, and installer lock path, then exits before downloading, verifying, writing files, or touching the service manager. Dry-run exists for review and automation plans; the normal command above is the install/update command.

Advanced install paths

Preview the Linux/macOS host plan without changing the machine:

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

From an installed binary, preview or run the same update path:

oraclemcp --json self-update --dry-run --version 0.8.0
oraclemcp self-update --version 0.8.0 --no-service

On Windows, download and run the PowerShell installer:

iwr -UseBasicParsing https://raw.githubusercontent.com/MuhDur/oraclemcp/main/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -DryRun -Version 0.8.0
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Version 0.8.0

The Windows installer accepts the same release operations: -Update for the explicit update path, -NoService to suppress service prompts, and -Verify prefer, -Verify require, or -Verify checksum-only for the verification posture. prefer installs after a hard SHA-256 check when cosign is missing; require fails without cosign.

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Update -Version 0.8.0 -NoService

For air-gapped hosts, download the release archive plus its .sha256, .sig, .crt, and .attestation.sigstore.json siblings, then run a downloaded copy of the installer:

bash install.sh --offline ./oraclemcp-x86_64-unknown-linux-musl.tar.gz --version 0.8.0

powershell -ExecutionPolicy Bypass -File .\install.ps1 `
  -Offline .\oraclemcp-x86_64-pc-windows-msvc.zip -Version 0.8.0

The release installer does not silently fall back from a missing release archive to a source build. Use --source explicitly when you want cargo install instead of the verified archive path.

On Linux the installer auto-detects the static musl build, which runs everywhere (including WSL2). The published glibc tarballs are also installable, but only by explicit request: --target x86_64-unknown-linux-gnu (or aarch64-unknown-linux-gnu).

Uninstall is preview-first and idempotent. Service removal remains an explicit service-manager mutation:

bash install.sh --uninstall --dry-run
bash install.sh --uninstall --yes
bash install.sh --uninstall --service --yes

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall -DryRun
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall -Yes

Install the local service only with explicit consent. Keep it on loopback unless you deliberately configure remote HTTP, and use service-owned client credentials, OAuth, or mTLS for HTTP MCP clients. For Windows service install, the PowerShell installer also requires explicit consent.

oraclemcp --json service install --dry-run --profile db_ro --listen 127.0.0.1:7070 --client-credentials
oraclemcp service install --yes --profile db_ro --listen 127.0.0.1:7070 --client-credentials
oraclemcp --json clients issue --label claude --scope oracle:read

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Service -Yes -Profile db_ro

Open the operator dashboard through the paired browser flow:

om dashboard

The dashboard uses a one-time loopback pairing ticket, then an HttpOnly SameSite=Strict cookie plus CSRF and route-scoped action tickets. Browser requests do not supply the database Subject: the server derives the Subject from the authenticated transport principal, session, and lane context. Authenticated HTTP sessions run on isolated per-principal lanes with their own Oracle connection, operating level, grants, cancellation, and audit context. Intentional --allow-no-auth HTTP development uses one anonymous lane; stdio remains the single local client path.

Other release channels come from the same signed archive matrix. These channels can lag the GitHub release tag, so use the check command first and install only after it resolves the target version.

cargo binstall oraclemcp
docker run -i --rm ghcr.io/muhdur/oraclemcp:0.8.0

Pending registry-backed channels:

brew info MuhDur/oraclemcp/oraclemcp
winget search --id MuhDur.oraclemcp --exact

After the relevant check resolves the target version, these commands are copy-pasteable:

brew install MuhDur/oraclemcp/oraclemcp
winget install --id MuhDur.oraclemcp --exact

An npm/npx channel is not offered. Install with the one-line installer above, or cargo binstall oraclemcp, the GHCR Docker image, or the Homebrew/winget channels once they resolve.

Why oraclemcp

• Fail-closed by construction. A SELECT that an agent dreams up should never silently turn into a DELETE. Each raw statement runs through the hardened classifier. Read tools admit only proven read-only SELECT/WITH and dictionary introspection. Non-read execution is isolated in oracle_execute, bounded by profile max_level/default_level, rollback-by-default for DML, and explicit-confirm-before-commit. Temporary elevation through oracle_set_session_level can never exceed the profile ceiling. Forbidden constructs (multi-statement batches, string-concat dynamic SQL, an unproven function call inside a SELECT) are rejected before touching the database, with an OperatingLevelTooLow or ForbiddenStatement 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) so clients do not infer unsafe defaults. Errors are structured [ErrorEnvelope](crates/oraclemcp-error)s with machine-stable classes, fuzzy suggestions, and next-step hints, not bare strings. A zero-arg oracle_capabilities tool lets an agent discover the surface; MCP resources expose the capability/tool documents plus schema/object read templates; and an offline build degrades to a RuntimeStateRequired contract instead of crashing.
• Pure Rust, no unsafe. Every crate is #![forbid(unsafe_code)]; the fail-closed classifier 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.

Source builds and runtime requirements

This branch is pinned to nightly-2026-05-11. The thin-native line has no stable MSRV because asupersync 0.3.4 uses nightly-only language features (#![feature(try_trait_v2)] and try_trait_v2_residual); the pinned oracledb 0.8.0 driver itself is stable-clean. The repository's rust-toolchain.toml selects the pin for local builds. Use the release installer above when you want the prebuilt binary; use cargo install only when you intentionally want a source build.

rustup toolchain install nightly-2026-05-11 --component rustfmt --component clippy

Direct source install:

cargo +nightly-2026-05-11 install oraclemcp

Live database access is built in through the pure-Rust thin oracledb driver.

Runtime requirements for live database access:

• Optionally TNS_ADMIN pointing at a directory with tnsnames.ora if you connect by net-service name.

No Oracle Instant Client, ODPI-C library, or C toolchain is required by the driver.

Use oraclemcp --json doctor to verify the binary and offline setup, oraclemcp --json doctor --profile to inspect non-secret profile metadata without resolving secrets, and oraclemcp --json doctor --online --profile to add live connectivity, authentication, role/open-mode, standby, and privilege checks. Doctor output is safe to paste into agent sessions: it omits connect strings, usernames, credential_ref values, passwords, proxy identities, wallet passwords, IAM tokens, wallet paths, and server DNs while keeping structured failure classes and ORA codes visible.

Generate generic local setup templates for profiles, wrappers, and MCP client snippets:

oraclemcp --json setup --profile db_ro

To create a minimal starter profiles file directly, use the same config-ops backend the dashboard uses. This validates the draft, writes a backup, atomically replaces the target, and reports the reload/rollback metadata without echoing the raw profile TOML:

oraclemcp --json setup --write --profile db_ro

Docker: a ready-to-run thin-driver image, published to GHCR and listed in the MCP registry on release as io.github.MuhDur/oraclemcp. Mount a profiles config and pass the credential the profile's credential_ref expects:

docker run -i --rm \
  -v "$HOME/.config/oraclemcp:/root/.config/oraclemcp:ro" \
  -e ORACLE_APP_PASSWORD \
  ghcr.io/muhdur/oraclemcp:0.8.0          # MCP over stdio, against the configured profile

docker run -i --rm ghcr.io/muhdur/oraclemcp:0.8.0   # tool surface only (no DB)

An optional PL/SQL intelligence image is available from the manual Docker workflow. It is the same server compiled with --features plsql-intelligence; it can start without a database connection and advertises the offline oracle_plsql_* tools immediately. Live PL/SQL tools still require a profile.

docker run -i --rm ghcr.io/muhdur/oraclemcp:0.8.0-plsql-intelligence --json info
docker run -i --rm ghcr.io/muhdur/oraclemcp:0.8.0-plsql-intelligence capabilities

Local feature-image builds resolve the PL/SQL engine crates from crates.io:

docker buildx build \
  --target runtime-plsql-intelligence \
  -t oraclemcp:plsql-intelligence .
docker run -i --rm oraclemcp:plsql-intelligence --json info

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

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

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

For Codex-style TOML config, the same command is:

[mcp_servers.oracle]
command = "oraclemcp"
args = ["serve", "--profile", "db_ro", "--allow-no-auth"]

Or run it directly:

oraclemcp serve                      # stdio (default); --allow-no-auth for local dev
oraclemcp --json clients issue --label claude --scope oracle:read  # shown-once HTTP bearer
oraclemcp serve --listen 127.0.0.1:7070 --client-credentials --profile db_ro
oraclemcp serve --listen 127.0.0.1:7070 --allow-no-auth   # local HTTP dev only
oraclemcp --json setup --profile db_ro    # generic onboarding templates
oraclemcp --json setup --write --profile db_ro  # write starter profiles via SCFG
oraclemcp capabilities               # the advertised tool surface + feature tiers (JSON)
oraclemcp --json profiles            # configured profile names and non-secret metadata
oraclemcp doctor                     # offline diagnostics (thin driver, TNS/wallet, classifier, NLS)
oraclemcp doctor --profile dev_ro    # inspect profile metadata offline
oraclemcp doctor --online --profile dev_ro  # include live connectivity/auth/role/privilege checks
oraclemcp info                       # build info: version, tools, transports, thin DB
oraclemcp robot-docs guide           # compact in-binary guide for agents
oraclemcp completions bash           # shell completions: bash, zsh, fish, powershell
oraclemcp --json se

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MuhDur](https://github.com/MuhDur)
- **Source:** [MuhDur/oraclemcp](https://github.com/MuhDur/oraclemcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.