Oracle Context MCP Server

Production-ready OCI MCP (Model Context Protocol) server with 69 tools across 22 OCI services. Gives AI agents (Claude Desktop, Cursor, VS Code, OCI GenAI) secure, natural-language access to your Oracle Cloud Infrastructure.

One-Line Install (Claude Desktop / Cursor)

uvx oci-context-mcp --print-config

This prints the ready-to-paste mcpServers block for your claude_desktop_config.json:

{
  "mcpServers": {
    "oci": {
      "command": "uvx",
      "args": ["oci-context-mcp", "--transport", "stdio"],
      "env": {
        "OCI_COMPARTMENT_ID": "ocid1.compartment.oc1...",
        "OCI_REGION": "us-phoenix-1"
      }
    }
  }
}

Paste it into:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: .cursor/mcp.json in your project root
• VS Code: .vscode/mcp.json

Requires uv (brew install uv on macOS). Your ~/.oci/config is used automatically for auth when not running on OCI.

Features

• 28 Production Tools across:

  • Compute (list instances, shapes, details)
  • Object Storage (namespaces, buckets, objects)
  • Networking (VCNs, subnets, security lists, route tables)
  • Identity & IAM (compartments, users, groups, policies)
  • Database (Autonomous DB, DB Systems)
  • Block & File Storage (volumes, file systems)
  • Resource Search (free-text search)
  • Vault & Secrets
  • Monitoring (usage/cost)
  • Health & Tenancy info

• Deep OCI IAM Integration:

  • Instance Principal (keyless, recommended for OCI hosting)
  • Config file fallback for local development
  • IAM policy validation hooks

• Production Ready:

  • FastAPI + MCP protocol
  • Async/await throughout
  • Comprehensive error handling
  • Logging with rotation
  • CORS-enabled
  • Environment-driven config

Quick Start

Local Development

# Set environment
export OCI_COMPARTMENT_ID=ocid1.compartment.oc1...
export OCI_REGION=us-phoenix-1
export LOG_LEVEL=INFO

# Install dependencies
pip install -r requirements.txt

# Run server
python mcp_server.py

Server runs on http://localhost:8000

• Health check: http://localhost:8000/health
• MCP endpoint: http://localhost:8000/mcp

Docker Deployment

# Build image
docker build -t oci-context-mcp:latest .

# Push to OCIR
docker tag oci-context-mcp:latest ocir.us-phoenix-1.ocir.io/YOUR_TENANCY/oci-context-mcp:latest
docker push ocir.us-phoenix-1.ocir.io/YOUR_TENANCY/oci-context-mcp:latest

OCI Infrastructure Deployment

cd infra

# Initialize Terraform
terraform init

# Plan deployment
terraform plan -var-file=terraform.tfvars

# Deploy
terraform apply -var-file=terraform.tfvars

Tool Inventory

* supports compartment_scope: single (default) | recursive | tenancy

Connecting OCI Generative AI Agent

1. Push Docker image to OCIR
2. Deploy with Terraform (creates Container Instance)
3. In OCI Console, go to Generative AI > Agents
4. Create agent
5. Add tool > Custom > Model Context Protocol
6. Configure:
   • Remote MCP Server: http://<container-instance-ip>:8000/mcp
   • Authentication: Instance Principal
   • Audience: (leave default or use tenancy ID)
7. Connect and test

Architecture

AI Agent (OCI GenAI, LangChain, etc.)
    ↓
OCI API Gateway (optional WAF/rate limiting)
    ↓
MCP Protocol Endpoint (/mcp)
    ↓
Oracle Context Server (FastAPI)
    ↓
OCI AuthManager (Instance Principal)
    ↓
OCI SDK Clients (Compute, Storage, Identity, etc.)

Environment Variables

OCI_COMPARTMENT_ID  # Compartment OCID for queries
OCI_REGION          # OCI region (default: us-phoenix-1)
LOG_LEVEL           # Logging level (default: INFO)

API References

• OCI SDK for Python
• Model Context Protocol
• OCI Generative AI Service

Security

• Instance Principal auth (no hardcoded credentials)
• IAM policies enforce least-privilege
• CORS restricted in production (update allow_origins)
• All secrets from environment variables
• Logging does not log sensitive data (set verbose: 0 for credentials)

Troubleshooting

Instance Principal not available locally?

• Use ~/.oci/config file
• Set OCI_CONFIG_FILE env var if needed

Compartment ID errors?

• Verify OCI_COMPARTMENT_ID env var is set
• Check IAM policies for dynamic group

Container Instance not responding?

• Check terraform output mcp_server_url
• Verify subnet has egress rules
• Check Container Instance logs in OCI Console

License

MIT

Telemetry

By default the server writes one JSON line per tool call to oci_mcp_metrics.jsonl on the host. No data leaves your machine.

Each event records: tool, ok, ms, version, and a one-way hash of your region (not the OCID). No compartment IDs, no credentials, no query content.

# Ask the agent directly
get_metrics_summary()

# Or inspect the raw file
cat oci_mcp_metrics.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, calls: length})'

To disable: OCI_MCP_TELEMETRY=off in your environment or .env file.

Coverage vs OCI CLI

The OCI CLI exposes ~130 service groups. This server covers ~13% (the highest-traffic read paths).

See BUILD_PLAN.md for the full F1–F7 roadmap toward parity with Azure MCP.

Roadmap

• F1: STDIO transport + uvx oci-context-mcp packaging (v2.1)
• F2: IAM compartment tree traversal (recursive multi-compartment) (v2.2)
• F3: Monitoring (metrics, alarms, log search) (v2.3)
• 69 tools across 22 OCI services (v2.5)
• F4: Write operations with confirmation + rollback
• F5: Multi-region fan-out
• F6: Plugin SDK for custom tools
• F7: OCI Console SSO / browser auth