MCP Server Oci

🚀 MCP Server for Oracle Cloud Infrastructure (OCI)

This project develops a Model Context Protocol (MCP) server tailored for Oracle Cloud Infrastructure. It enables Large Language Models (LLMs), such as Claude, to directly interact with OCI resources, facilitating seamless resource management and utilization.

🚀 Quick Start

This MCP server allows LLMs like Claude to interact with Oracle Cloud Infrastructure resources. Before you start, ensure you meet the Prerequisites and follow the Installation steps.

✨ Features

• Dynamic Profile Selection: Switch between OCI profiles/tenancies without restarting the server.
• Standard OCI CLI Configuration: Connect to Oracle Cloud using the standard OCI CLI configuration.
• Comprehensive Resource Management: Utilize a set of tools to list and manage OCI resources.
• Instance Lifecycle Management: Start and stop OCI instances.
• Database Systems and DB Nodes Management: Manage Database Systems and DB Nodes.
• MCP Protocol Integration: Integrate with the MCP protocol to enable access from Claude Desktop.

📦 Installation

First, clone this repository:

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

💻 Usage Examples

Starting the Server

Basic Usage

Option 1: Dynamic Profile Selection (Recommended) Start the server without specifying a profile and select it at runtime:

python -m mcp_server_oci.mcp_server

Then, use the following MCP tools to manage profiles:

• list_oci_profiles: View available profiles from ~/.oci/config.
• set_oci_profile: Activate a specific profile.
• get_current_oci_profile: Check the currently active profile.

Option 2: With Default Profile Start the server with a pre - loaded specific profile:

python -m mcp_server_oci.mcp_server --profile DEFAULT

Using uv:

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

Advanced Usage

Switching Between Tenancies

You can switch between different OCI tenancies without restarting the server:

# 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 the following configuration to your /Users/<usuario>/Library/Application Support/Claude/claude_desktop_config.json file:

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 the 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"

🔧 Technical Details

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: A complete guide for multi - tenancy support.
• Error Handling Pattern: A developer guide for error handling.
• Error Handling Examples: Practical examples.

🤝 Contributing

Contributions are welcome! The codebase adheres to the following 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]