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.

presentation

Features

Dynamic Profile Selection: Switch between OCI profiles/tenancies without restarting the server
Connection to Oracle Cloud using standard OCI CLI configuration
85 comprehensive tools to list and manage OCI resources across 11+ service categories
Instance lifecycle management (start, stop)
Database Systems and DB Nodes management
Container Engine for Kubernetes (OKE) cluster and node pool 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

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

Compartments

list_compartments - List all compartments accessible to you

Users

list_users - List all IAM users in a compartment with capabilities and MFA status
get_user - Get detailed user information including group memberships

Groups

list_groups - List all IAM groups in a compartment with member count
get_group - Get detailed group information including members

Policies

list_policies - List all IAM policies in a compartment with statements
get_policy - Get detailed policy information with all policy statements

Dynamic Groups

list_dynamic_groups - List all dynamic groups with matching rules
get_dynamic_group - Get detailed dynamic group info with instance principal rules

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)

Databases 🔥

DB 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

Regular Databases 🆕

list_databases - List databases in a compartment (optionally filtered by DB System)
get_database - Get detailed database information including connection strings and PDB name

Autonomous Databases 🆕

list_autonomous_databases - List Autonomous Databases with workload type and connection info
get_autonomous_database - Get detailed ADB info including wallet info and auto-scaling settings

Networking

Virtual Cloud Networks (VCNs)

list_vcns - List all VCNs in a compartment with CIDR blocks and DNS info
get_vcn - Get detailed VCN information including IPv6 CIDR blocks

Subnets

list_subnets - List all subnets in a compartment (optionally filtered by VCN)
get_subnet - Get detailed subnet information with security lists and routing

Virtual Network Interface Cards (VNICs)

list_vnics - List all VNICs in a compartment (optionally filtered by instance)
get_vnic - Get detailed VNIC information including IP addresses and NSG associations

Security

list_security_lists - List security lists with ingress/egress rules (optionally filtered by VCN)
get_security_list - Get detailed security list with all rules
list_network_security_groups - List Network Security Groups (NSGs) in a compartment
get_network_security_group - Get detailed NSG information with all security rules

Storage 🆕

Object Storage

get_namespace - Get the Object Storage namespace for the tenancy
list_buckets - List all Object Storage buckets in a compartment
get_bucket - Get detailed bucket information including public access settings and versioning

Block Storage

list_volumes - List all Block Storage volumes in a compartment
get_volume - Get detailed volume information including size, performance tier, and backup policy
list_boot_volumes - List all boot volumes in a compartment (optionally filtered by AD)
get_boot_volume - Get detailed boot volume information including source image

File Storage

list_file_systems - List all File Storage file systems in a compartment and AD
get_file_system - Get detailed file system information including metered bytes and snapshots

Load Balancers 🆕

Classic Load Balancers

list_load_balancers - List all classic load balancers in a compartment
get_load_balancer - Get detailed load balancer information including backend sets, listeners, and certificates

Network Load Balancers

list_network_load_balancers - List all network load balancers in a compartment
get_network_load_balancer - Get detailed network load balancer information including backend sets and listeners

Infrastructure Utilities 🆕

Availability and Fault Domains

list_availability_domains - List all availability domains in a compartment
list_fault_domains - List all fault domains in an availability domain

Compute Images

list_images - List all compute images with OS, version, and size
get_image - Get detailed image information including launch options

Compute Shapes

list_shapes - List all compute shapes with CPU, memory, network, and GPU specs

Regions and Tenancy

list_regions - List all available OCI regions
get_tenancy_info - Get tenancy details including name and home region

Security & Encryption 🆕

KMS Vaults

list_vaults - List all KMS vaults in a compartment
get_vault - Get detailed vault information including crypto and management endpoints

Encryption Keys

list_keys - List all encryption keys in a vault's compartment
get_key - Get detailed key information including algorithm, shape, and versions

Cost Management 🆕

Usage and Cost Analysis

get_cost_usage_summary - Get cost and usage summary for a tenancy with daily or monthly granularity
get_cost_by_service - Get cost breakdown by service for a specified time period
get_cost_by_compartment - Get cost breakdown by compartment for a specified time period

Budgets

list_budgets - List all budgets with amount, actual spend, and forecasted spend
get_budget - Get detailed budget information including targets and alert rules

Monitoring & Observability 🆕

Alarms

list_alarms - List all alarms with query, severity, and destinations
get_alarm - Get detailed alarm information including thresholds and notification settings
get_alarm_history - Get alarm state history with timestamps and state transitions

Metrics

list_metrics - List available metrics with namespaces and dimensions
query_metric_data - Query metric data for a time range using MQL

Logs

search_logs - Search logs using the Logging Search API
list_log_groups - List all log groups in a compartment
list_logs - List all logs in a log group with types and retention

Container Engine for Kubernetes (OKE) 🆕

Clusters

list_oke_clusters - List all OKE clusters with Kubernetes version and endpoints
get_oke_cluster - Get detailed cluster info including network config, add-ons, and available upgrades
get_oke_cluster_kubeconfig - Get kubeconfig file content for kubectl access

Node Pools

list_oke_node_pools - List node pools with shape, image, and placement configuration
get_oke_node_pool - Get detailed node pool info including individual nodes, eviction settings, and cycling details

Work Requests

list_oke_work_requests - List async operations (create, update, delete) for OKE resources
get_oke_work_request - Get detailed work request status and progress

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

Identity & Access Management 🆕

# Users "List all IAM users in my tenancy" "Show me details for user ocid1.user.oc1..." "Does this user have MFA enabled?" "What groups is this user a member of?" # Groups "List all IAM groups in compartment X" "Show me members of group 'Administrators'" "Get details for group ocid1.group.oc1..." # Policies "List all IAM policies in the root compartment" "Show me policy statements for 'network-admins-policy'" "What permissions does this policy grant?" "Get details for policy ocid1.policy.oc1..." # Dynamic Groups "List all dynamic groups in my tenancy" "Show me matching rules for dynamic group 'instance-principals'" "What instances match this dynamic group?" "Get details for dynamic group ocid1.dynamicgroup.oc1..." # Security auditing "Which users have admin access?" "Show me all policies that grant object storage access" "What dynamic groups allow instance principals?"

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 Management

# DB Systems "Show me all DB Systems in compartment ocid1.compartment.oc1..." "Get details for DB System ocid1.dbsystem.oc1..." # DB Nodes management "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 DB Node ocid1.dbnode.oc1..." "Soft reset DB Node ocid1.dbnode.oc1..." # Regular Databases 🆕 "List all databases in compartment X" "Show me databases in DB System Y" "Get connection strings for database ocid1.database.oc1..." "What is the character set and PDB name of this database?" # Autonomous Databases 🆕 "List all Autonomous Databases in compartment Z" "Show me details for ADB ocid1.autonomousdatabase.oc1..." "What workload type is this Autonomous Database?" "Get connection strings and wallet info for this ADB" "Is auto-scaling enabled on this Autonomous Database?"

Networking Management

# VCN operations "List all VCNs in compartment ocid1.compartment.oc1..." "Show me details for VCN ocid1.vcn.oc1..." # Subnet operations "List all subnets in VCN ocid1.vcn.oc1..." "Get details for subnet ocid1.subnet.oc1..." # Security operations "Show me all security lists in compartment X" "List all network security groups in VCN Y" "Get security rules for security list ocid1.securitylist.oc1..." # VNIC operations "List all VNICs for instance ocid1.instance.oc1..." "Show me details for VNIC ocid1.vnic.oc1..."

Storage Management 🆕

# Object Storage operations "What is my Object Storage namespace?" "List all buckets in compartment X" "Show me details for bucket 'my-data-bucket'" "Is bucket 'public-bucket' publicly accessible?" # Block Storage operations "List all volumes in compartment Y" "Show me details for volume ocid1.volume.oc1..." "List all boot volumes in compartment Z" "What is the size and performance tier of this volume?" # File Storage operations "List all file systems in compartment W and AD-1" "Show me details for file system ocid1.filesystem.oc1..." "How many bytes is this file system using?"

Load Balancer Management 🆕

# Classic Load Balancers "List all load balancers in compartment X" "Show me details for load balancer ocid1.loadbalancer.oc1..." "What backend sets and listeners does this load balancer have?" "Show me health check configuration for this load balancer" # Network Load Balancers "List all network load balancers in compartment Y" "Show me details for network load balancer ocid1.networkloadbalancer.oc1..." "What is the backend configuration for this NLB?" "Is source IP preservation enabled on this network load balancer?" # Load balancer analysis "Show me all load balancers and their IP addresses" "Which load balancers are private vs public?"

Infrastructure Utilities 🆕

# Availability and Fault Domains "List all availability domains in my tenancy" "Show me fault domains in availability domain AD-1" "What availability domains are available in region us-ashburn-1?" # Compute Images "List all compute images in compartment X" "Show me details for image ocid1.image.oc1..." "What Oracle Linux images are available?" "What is the size and OS version of this image?" # Compute Shapes "List all compute shapes available in compartment Y" "What shapes support GPU?" "Show me flexible shapes with configurable OCPUs" "What is the memory and network bandwidth for shape VM.Standard.E4.Flex?" # Regions and Tenancy "List all available OCI regions" "What is my tenancy name and home region?" "Show me tenancy information"

Security & Encryption 🆕

# KMS Vaults "List all vaults in compartment X" "Show me details for vault ocid1.vault.oc1..." "What is the management endpoint for this vault?" "Is this vault primary or replica?" # Encryption Keys "List all encryption keys in vault Y" "Show me details for key ocid1.key.oc1..." "What algorithm and protection mode does this key use?" "What is the current key version?" # Key management workflow "First, get vault details to obtain the management_endpoint" "Then, use that endpoint to list or get keys in that vault"

Cost Management 🆕

# Usage and Cost Analysis "Show me cost and usage summary for the last 30 days" "Get cost breakdown by service from 2024-01-01 to 2024-01-31" "What are my costs by compartment for this month?" "Show me daily cost summary for my tenancy" # Cost analysis queries "Which services are costing the most?" "What compartment has the highest spend?" "Show me monthly cost trends" # Budgets "List all budgets in compartment X" "Show me budget details for budget ocid1.budget.oc1..." "What is my actual spend vs budget?" "Show me forecasted spend for this budget" "Which budgets have alert rules configured?"

Monitoring & Observability 🆕

# Alarms "List all alarms in compartment X" "Show me details for alarm ocid1.alarm.oc1..." "What alarms are currently firing?" "Show me alarm history for the last 24 hours" "Which alarms have critical severity?" # Metrics "List all available metrics in compartment Y" "Show me CPU metrics for compute instances" "Query CpuUtilization for the last hour" "What metrics are available for namespace oci_computeagent?" # Logs "Search logs for errors in the last hour" "List all log groups in compartment Z" "Show me logs in log group ocid1.loggroup.oc1..." "Search for 'ERROR' in application logs" # Troubleshooting workflows "Show me all firing alarms and their metric queries" "Get CPU utilization data for instance X in the last 2 hours" "Search logs for errors related to database connections"

Container Engine for Kubernetes (OKE) 🆕

# Clusters "List all OKE clusters in compartment X" "Show me details for cluster ocid1.cluster.oc1..." "What Kubernetes version is this cluster running?" "What upgrades are available for my cluster?" "Get the kubeconfig for cluster ocid1.cluster.oc1..." "What are the public and private endpoints for this cluster?" # Node Pools "List all node pools in compartment Y" "Show me node pools for cluster Z" "Get details for node pool ocid1.nodepool.oc1..." "What is the shape and size of this node pool?" "Show me individual nodes in this node pool" "What is the Kubernetes version of the node pool?" # Work Requests "List all OKE work requests in compartment A" "Show me work requests for cluster B" "Get details for work request ocid1.clustersworkrequest.oc1..." "What operations are currently in progress?" "Show me the status of cluster creation" # Kubernetes cluster management workflows "List all clusters and their Kubernetes versions" "Show me clusters that have available upgrades" "Get kubeconfig for all clusters in my compartment" "Which node pools are running outdated Kubernetes versions?" "Show me all work requests that failed"

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" "Show me the complete network topology for compartment X"

🚀 Recent Improvements

v1.15 - Container Engine for Kubernetes (OKE) Tools (Latest) ☸️

7 new OKE tools: Clusters, Node Pools, and Work Requests
Clusters: List/get clusters with Kubernetes version, endpoints, network config, and available upgrades
Kubeconfig: Get kubeconfig file content for kubectl access to clusters
Node Pools: List/get node pools with detailed node information, placement config, and eviction settings
Work Requests: Track async operations (create, update, delete) for OKE resources
Essential for managing Kubernetes infrastructure on OCI
Total MCP tools increased from 78 to 85
Added comprehensive OKE usage examples in README

v1.14 - Monitoring & Observability Tools 🔍

8 new monitoring tools: Alarms, Metrics, and Logs
Alarms: List/get alarms with severity, query history, and state transitions
Metrics: List metrics, query time-series data with MQL for performance analysis
Logs: Search logs, list log groups and logs for troubleshooting
Essential for real-time monitoring, troubleshooting, and incident response
Total MCP tools increased from 70 to 78
Added comprehensive monitoring & observability usage examples in README

v1.13 - Cost Management Tools 💰

5 new cost management tools: Usage/Cost Analysis and Budgets
Usage Analysis: Get cost summaries with daily/monthly granularity
Cost Breakdown: Analyze costs by service or compartment for any time period
Budget Management: List/get budgets with actual spend, forecasted spend, and alert rules
Essential for cost optimization, budget tracking, and financial governance
Total MCP tools increased from 65 to 70
Added comprehensive cost management usage examples in README

v1.12 - Security & Encryption Tools 🔐

4 new security tools: KMS Vaults and Encryption Keys
KMS Vaults: List/get vaults with crypto and management endpoints
Encryption Keys: List/get keys with algorithm, protection mode, and key shape
Complete KMS coverage: Vault management and key discovery
Dynamic KMS Management client creation using vault endpoints
Total MCP tools increased from 61 to 65
Added comprehensive security & encryption usage examples in README

v1.11 - Infrastructure Utilities 🏗️

7 new infrastructure tools: Availability Domains, Fault Domains, Images, Shapes, Regions, and Tenancy
Availability/Fault Domains: List ADs and FDs for high availability planning
Compute Images: List/get images with OS versions and launch options
Compute Shapes: List shapes with CPU, memory, network, and GPU specifications
Regions & Tenancy: List all regions and get tenancy information
Essential for resource planning, capacity management, and infrastructure discovery
Total MCP tools increased from 54 to 61
Added comprehensive infrastructure utilities usage examples in README

v1.10 - Load Balancer Tools ⚖️

4 new load balancer tools: Classic Load Balancers and Network Load Balancers
Classic Load Balancers: List/get LBs with backend sets, listeners, and certificates
Network Load Balancers: List/get NLBs with backend configuration and IP preservation
Complete load balancing coverage: Layer 7 (classic) and Layer 4 (network) load balancers
Total MCP tools increased from 50 to 54
Added comprehensive load balancer usage examples in README

v1.9 - Identity & Access Management Tools 🔐

8 new IAM tools: Users, Groups, Policies, Dynamic Groups
Security auditing: Review user capabilities, MFA status, and group memberships
Policy management: List and inspect all IAM policy statements
Dynamic groups: View instance principal matching rules
Essential for compliance, security audits, and access troubleshooting
Total MCP tools increased from 42 to 50
Added comprehensive IAM usage examples in README

v1.8 - Database Tools 🗄️

4 new database tools: Regular Databases and Autonomous Databases
Regular Databases: List/get databases with connection strings and PDB names
Autonomous Databases: List/get ADB with workload type, wallet info, and auto-scaling
Complete database ecosystem coverage: DB Systems, DB Nodes, Databases, and ADB
Total MCP tools increased from 38 to 42
Added comprehensive database usage examples in README

v1.7 - Storage Tools 💾

9 new storage tools: Object Storage, Block Storage, File Storage
Object Storage: Get namespace, list/get buckets with public access info
Block Storage: List/get volumes and boot volumes with performance tiers
File Storage: List/get file systems with metered bytes
Total MCP tools increased from 29 to 38
Added comprehensive storage usage examples in README

v1.6 - Comprehensive Networking Tools 🌐

10 new networking tools: VCNs, Subnets, VNICs, Security Lists, NSGs
Network topology discovery: Complete visibility of network infrastructure
Security auditing: Review security rules and network access controls
Connectivity troubleshooting: VNIC and routing information
Total MCP tools increased from 19 to 29
Added comprehensive networking usage examples in README

v1.5 - Dynamic Profile Selection 🔥

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]