oci-mcp

Operate Oracle Cloud Infrastructure from an AI agent.

An MCP server that exposes OCI — compute, block storage, networking, OKE, database, object storage and identity — as tools an agent can call, so you can ask for things instead of assembling oci CLI invocations and copying OCIDs between them.

"which of my instances are running?"
"what's in the test-deploy-kubeflow compartment?"
"show me the config for my OKE cluster"

It runs locally over stdio and reads credentials straight from ~/.oci/config, so they never leave your machine.

Demo

Ask in plain language; the agent picks the tool. No compartment was given here, so it swept the whole tenancy and tagged every row with where it came from:

oci_whoami reports the active tenancy and the server's own permissions — writes are impossible until you name an allowlisted compartment:

OKE clusters are invisible to OCI Resource Search, so oci_list is the way to reach them. The tool says so in its own output:

Output above is real, captured from a live tenancy. All identifiers — OCIDs, e-mail, tenancy name, public IPs, and the OCID fragments embedded in OKE node names — were replaced with placeholders before rendering.

Status: read-only today. Create and modify tools are planned — see open issues.

Related MCP server: mcp-server-oci

Requirements

• Python 3.12 — pinned in .python-version; uv fetches it. The oci SDK does not support 3.14.

• uv

• A working ~/.oci/config. Verify with oci iam region-list.

Install

git clone https://github.com/jaiakash/oracle-cloud-mcp.git
cd oracle-cloud-mcp
uv sync

Run

uv run oci-mcp

This speaks MCP over stdio, so on its own it just waits on stdin — that is correct, not a hang. Normally your client launches it.

Add to your MCP client

Claude Code:

claude mcp add oci -- uv --directory "$PWD" run oci-mcp

Cursor, VS Code, Zed and others take the same command as JSON:

{
  "mcpServers": {
    "oci": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/oracle-cloud-mcp", "run", "oci-mcp"]
    }
  }
}

A stdio server inherits nothing from your shell, so any setting from Configure has to be passed by the client:

claude mcp add oci --env OCI_MCP_COMPARTMENTS=lab -- uv --directory "$PWD" run oci-mcp

Confirm it connected by asking the agent to call oci_whoami.

Tools

Reads collapse into three dispatch tools because their schemas are uniform: "show me type in compartment". Results are projected down to the fields that identify and locate a resource — an OCI Instance has 36 fields, most of them null — with verbose=true to get the full object.

Resource types

Pass any of these as resource_type:

Two quirks worth knowing:

• OKE clusters are not indexed by OCI Resource Search, so oci_search will never return one. Use oci_list("cluster").

• Buckets are addressed by name, not OCID: oci_get("bucket", "my-bucket").

Configure

Everything is an environment variable, and every default is safe. See .env.example.

The allowlist fails closed: an unconfigured server cannot mutate anything, anywhere. Name a disposable compartment to enable writes — never the root. A disabled capability's tools are absent from the catalog entirely rather than present and refusing, so an agent cannot be talked into calling one.

oci_whoami reports the active allowlist and flags, and explains why a mutation would be refused.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Adding a new resource type is usually a single entry in registry.py and the test suite covers it automatically, which makes it a good first change.

License

Apache License 2.0.