OCI MCP Server

# 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 - **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 ```bash 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: ```bash 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: ```bash python -m mcp_server_oci.mcp_server --profile DEFAULT ``` With `uv`: ```bash 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: ```bash # 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):** ```json "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:** ```json "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:** ```json "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** ```bash # 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** 🆕 ```bash # 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** ```bash # 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** ```bash # 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** ```bash # 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** 🆕 ```bash # 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** 🆕 ```bash # 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** 🆕 ```bash # 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** 🆕 ```bash # 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** 🆕 ```bash # 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** 🆕 ```bash # 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)** 🆕 ```bash # 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** ```bash # 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](DYNAMIC_PROFILE_SELECTION.md) - Complete guide for multi-tenancy support - [Error Handling Pattern](ERROR_HANDLING_PATTERN.md) - Developer guide for error handling - [Error Handling Examples](EXAMPLE_ERROR_HANDLING.py) - 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]