MCP Server for Oracle Cloud Infrastructure (OCI)

This project implements a Model Context Protocol (MCP) server for Oracle Cloud Infrastructure, allowing LLMs like Claude to interact directly with OCI resources.

Features

• Dynamic Profile Selection: Switch between OCI profiles/tenancies without restarting the server
• Connection to Oracle Cloud using standard OCI CLI configuration
• Comprehensive tools to list and manage OCI resources
• Instance lifecycle management (start, stop)
• Database Systems and DB Nodes management
• Integration with the MCP protocol to facilitate access from Claude Desktop

Prerequisites

• Python 3.10 or higher
• OCI CLI configured (oci setup config)
• Appropriate permissions in Oracle Cloud

Installation

Clone this repo

pip install git+https://github.com/modelcontextprotocol/python-sdk.git
pip install oci fastapi uvicorn click pydantic loguru
pip install -e .

Usage

Starting the Server

Option 1: Dynamic Profile Selection (Recommended)

Start without a profile and select it at runtime:

python -m mcp_server_oci.mcp_server

Then use the MCP tools to manage profiles:

• list_oci_profiles - See available profiles from ~/.oci/config
• set_oci_profile - Activate a specific profile
• get_current_oci_profile - Check which profile is active

Option 2: With Default Profile

Start with a specific profile pre-loaded:

python -m mcp_server_oci.mcp_server --profile DEFAULT

With uv:

uv --directory /path/to/mcp-server-oci run python -m mcp_server_oci.mcp_server --profile DEFAULT

Switching Between Tenancies

You can switch between different OCI tenancies without restarting:

# In your MCP client (e.g., Claude):
# 1. List available profiles
"Show me available OCI profiles"

# 2. Switch to a different tenancy
"Switch to the 'production' OCI profile"

# 3. Verify current profile
"What OCI profile am I using?"

Configuration for Claude Desktop (MacOS)

Add this configuration to your file: /Users/<usuario>/Library/Application Support/Claude/claude_desktop_config.json

With dynamic profile selection (recommended):

"mcpServers": {
  "mcp-server-oci": {
    "command": "python",
    "args": [
      "-m",
      "mcp_server_oci.mcp_server"
    ],
    "env": {
      "PYTHONPATH": "/<PATH_TO_MCP>/mcp-server-oci",
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

With fixed profile:

"mcpServers": {
  "mcp-server-oci": {
    "command": "python",
    "args": [
      "-m",
      "mcp_server_oci.mcp_server",
      "--profile", "DEFAULT"
    ],
    "env": {
      "PYTHONPATH": "/<PATH_TO_MCP>/mcp-server-oci",
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

With uv and dynamic profiles:

"mcpServers": {
  "mcp-server-oci": {
    "command": "uv",
    "args": [
      "--directory",
      "/<PATH_TO_MCP>/mcp-server-oci",
      "run",
      "python",
      "-m",
      "mcp_server_oci.mcp_server"
    ],
    "env": {
      "FASTMCP_LOG_LEVEL": "INFO"
    }
  }
}

📋 Available MCP Tools

Profile Management 🆕

• list_oci_profiles - List all available OCI profiles from ~/.oci/config
• set_oci_profile - Activate a specific profile for API calls
• get_current_oci_profile - Show currently active profile

Identity & Access Management

• list_compartments - List all compartments accessible to you

Compute Resources

• list_instances - List virtual machine instances in a compartment
• get_instance - Get detailed information about a specific instance
• start_instance - Start a stopped instance
• stop_instance - Stop a running instance (supports soft/force stop)

Database Systems 🔥

• list_db_systems - List DB Systems in a compartment
• get_db_system - Get detailed DB System information
• list_db_nodes - List DB Nodes in a compartment (optionally filtered by DB System)
• get_db_node - Get detailed DB Node information
• start_db_node - Start a stopped DB Node
• stop_db_node - Stop a running DB Node (soft or hard stop)
• reboot_db_node - Reboot a DB Node
• reset_db_node - Reset (force reboot) a DB Node
• softreset_db_node - Soft reset (graceful reboot) a DB Node
• start_db_system - Start all nodes of a DB System
• stop_db_system - Stop all nodes of a DB System

💡 Usage Examples

Profile Management

# From Claude or any MCP client:

# List available profiles
"Show me all available OCI profiles"

# Activate a specific profile
"Set the OCI profile to 'production'"

# Check current profile
"What OCI profile am I currently using?"

# Switch between tenancies
"Switch to the DEFAULT profile"

Compute Instance Management

# List instances
"Show me all compute instances in compartment ocid1.compartment.oc1..."

# Get instance details
"Get details for instance ocid1.instance.oc1..."

# Start/stop instances
"Start the instance ocid1.instance.oc1..."
"Stop the instance ocid1.instance.oc1... with force stop"

Database Systems Management

# List DB Systems
"Show me all DB Systems in compartment ocid1.compartment.oc1..."

# Get DB System details
"Get details for DB System ocid1.dbsystem.oc1..."

# Manage DB Nodes
"List all DB Nodes for DB System ocid1.dbsystem.oc1..."
"Start DB Node ocid1.dbnode.oc1..."
"Stop all nodes of DB System ocid1.dbsystem.oc1..."

# Reboot operations
"Reboot DB Node ocid1.dbnode.oc1..."
"Soft reset DB Node ocid1.dbnode.oc1..."

Resource Discovery

# List compartments
"List all compartments in my tenancy"

# Cross-resource queries
"Show me all running instances in compartment X"
"List all DB Systems and their current states"

🚀 Recent Improvements

v1.5 - Dynamic Profile Selection (Latest) 🔥

• Multi-tenancy support: Switch between OCI profiles without restarting
• New MCP tools: list_oci_profiles, set_oci_profile, get_current_oci_profile
• Profile requirement validation in all OCI tools
• Optional --profile argument (lazy initialization)
• Complete documentation in DYNAMIC_PROFILE_SELECTION.md
• Updated README with accurate tool listing

v1.4 - Centralized Configuration

• Created centralized config.py with all configuration constants
• Eliminated magic numbers throughout the codebase
• Improved maintainability and discoverability of configuration values

v1.3 - Async Operations

• Removed all blocking time.sleep() calls
• Made all operations truly asynchronous
• Improved server responsiveness

v1.2 - Standardized Error Handling

• Implemented Hybrid Error Handling Pattern
• Technical errors → raise exceptions
• Business states → return success dictionaries
• Comprehensive documentation in ERROR_HANDLING_PATTERN.md

v1.1 - DRY Principle

• Created mcp_tool_wrapper decorator
• Eliminated ~150 lines of repetitive code
• Consistent error handling and logging across all tools

v1.0 - Code Cleanup

• Removed unused/obsolete files
• Cleaned up commented code
• Established clean baseline

📚 Documentation

• Dynamic Profile Selection Guide - Complete guide for multi-tenancy support
• Error Handling Pattern - Developer guide for error handling
• Error Handling Examples - Practical examples

🤝 Contributing

Contributions are welcome! The codebase follows these patterns:

• Hybrid error handling (raise for technical errors, return dict for business states)
• Async operations (no blocking calls)
• Centralized configuration (constants in config.py)
• DRY principle (use decorators for common patterns)

📝 License

[Add your license here]