mcp-server-oci

jopsis/mcp-server-oci

3.2

If you are the rightful owner of mcp-server-oci and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Tools
5
Resources
0
Prompts
0

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

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

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

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.14 - Monitoring & Observability Tools (Latest) 🔍

  • 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

  • - Complete guide for multi-tenancy support
  • - Developer guide for error handling
  • - 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]