mcp-oci

Production-oriented MCP server for Oracle Cloud Infrastructure (OCI), exposing Compute, Networking and Object Storage operations to MCP clients (Claude Desktop, VS Code Copilot, Cursor, and compatible hosts).

Features

• Four authentication modes: config file (API key), inline API key, instance principal, and session token

• Per-call region override (region argument) on every Compute/Networking/Object Storage tool — query any OCI region without restarting the server

• Trimmed-by-default responses: list/get tools return a lean summary per resource instead of the full OCI SDK object (which can run 100+ fields deep, e.g. SSH keys and agent plugin configs on an instance); pass raw=true to get the untrimmed object

• Read-only enforcement independent of IAM policy: mutating tools can be blocked at the server level

• Compute instance discovery, VNIC inspection, and lifecycle actions

• Networking discovery: VCNs, subnets, security lists, NSGs, route tables

• Object Storage discovery and management: buckets and objects

• Environment-driven configuration for secure deployment

Related MCP server: OCI MCP Server

Available Tools

Tools marked Mutating are rejected by the server when OCI_READ_ONLY=true (the default), regardless of IAM permissions — a second layer of least-privilege enforcement on top of your OCI policies.

Tools marked Trimmed by default accept a raw boolean argument (default false) — set raw=true to get the untrimmed OCI SDK object instead of the summary (id, name, state, and the handful of fields that matter day-to-day).

Requirements

• Node.js 18+

• An OCI tenancy with credentials for one of the supported authentication modes

• Network connectivity from the MCP host to the OCI region endpoints

Configuration

Authentication mode

When a tool call omits compartmentId, it defaults to the tenancy root compartment (resolved from the auth provider). This doesn't work in instance_principal mode — the provider doesn't expose the tenancy OCID there, so compartmentId must be passed explicitly (use list_compartments to look it up by name first).

Compute, Networking and Object Storage resources are region-scoped in OCI. Every tool that touches them accepts an optional region argument (e.g. sa-vinhedo-1) to query a specific region without restarting the server; omitting it falls back to OCI_REGION or the config/session file's default region. list_compartments and list_regions are unaffected — compartments and region subscriptions are tenancy-wide, not regional.

config mode (API key via ~/.oci/config)

session mode (oci session authenticate token)

Uses the same OCI_CONFIG_FILE / OCI_CONFIG_PROFILE variables as config mode, pointing to a profile with a security_token_file.

apikey mode (inline API key, no config file)

* Provide either OCI_PRIVATE_KEY or OCI_PRIVATE_KEY_PATH.

instance_principal mode

No extra variables required — credentials are resolved from the instance metadata service. Only works when the MCP server itself runs on an OCI Compute instance (or OKE pod configured for it).

Transport

Usage

Run directly from GitHub

npx github:ferronicardoso/mcp-oci

Claude Code (CLI)

claude mcp add oci --scope user -- npx -y github:ferronicardoso/mcp-oci

--scope controls where the server registration is stored:

Environment variables (auth mode, OCI_READ_ONLY, etc.) can be passed with repeated --env KEY=VALUE flags before the --, e.g.:

claude mcp add oci --scope user \
  --env OCI_AUTH_MODE=config \
  --env OCI_CONFIG_PROFILE=DEFAULT \
  --env OCI_READ_ONLY=true \
  -- npx -y github:ferronicardoso/mcp-oci

Claude Desktop configuration

%APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "oci": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-oci"],
      "env": {
        "OCI_AUTH_MODE": "config",
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "OCI_READ_ONLY": "true"
      }
    }
  }
}

VS Code MCP configuration

.vscode/mcp.json:

{
  "servers": {
    "oci": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-oci"],
      "env": {
        "OCI_AUTH_MODE": "config",
        "OCI_CONFIG_PROFILE": "DEFAULT",
        "OCI_READ_ONLY": "true"
      }
    }
  }
}

Run with Docker (HTTP transport)

The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint (e.g. from n8n's MCP Client Tool node or any Streamable HTTP-compatible client):

docker run -d --name mcp-oci \
  -p 3003:3003 \
  -e OCI_AUTH_MODE=apikey \
  -e OCI_TENANCY_ID=ocid1.tenancy.oc1..xxxx \
  -e OCI_USER_ID=ocid1.user.oc1..xxxx \
  -e OCI_FINGERPRINT=xx:xx:xx:xx \
  -e OCI_REGION=sa-saopaulo-1 \
  -e OCI_PRIVATE_KEY_PATH=/keys/oci_api_key.pem \
  -e OCI_COMPARTMENT_ID=ocid1.compartment.oc1..xxxx \
  -e OCI_READ_ONLY=true \
  -v /path/to/oci_api_key.pem:/keys/oci_api_key.pem:ro \
  ghcr.io/ferronicardoso/mcp-oci:latest

The MCP endpoint is then available at http://localhost:3003/mcp.

Local Development

git clone https://github.com/ferronicardoso/mcp-oci
cd mcp-oci
npm install
npm run build

Start the compiled server:

npm start

Build and Commit Workflow

This repository intentionally tracks dist/ to support npx github:user/repo usage.

The project uses a Husky pre-commit hook to:

1. build TypeScript (npm run build)

2. stage generated artifacts (git add dist)

Manual fallback:

npm run build
git add dist

Security Notes

• Never commit real credentials, private keys, or .env files.

• OCI_READ_ONLY=true is the default; only set it to false for environments that must run mutating operations, and prefer pairing it with a least-privilege IAM policy on the OCI side.

• Prefer instance_principal authentication when the server runs on OCI Compute/OKE — it avoids storing long-lived credentials entirely.

• For apikey mode, prefer mounting the private key file (OCI_PRIVATE_KEY_PATH) over passing raw key content via OCI_PRIVATE_KEY.