Oracle Cloud Infrastructure (OCI) MCP Server

A comprehensive, robust, and highly extensible Model Context Protocol (MCP) server for managing Oracle Cloud Infrastructure (OCI) services. This server enables LLMs and MCP-compatible clients to securely interact with your Oracle Cloud account to manage compute instances, storage, identity, and databases.

🌟 Features

• Standardized Authentication: Automatically integrates with your existing OCI CLI configuration (~/.oci/config).
• Identity & Access Management (IAM): Manage compartments and list users across your tenancy.
• Compute & Networking: View Virtual Cloud Networks (VCNs), list instances, fetch details, and execute lifecycle operations (START, STOP, RESET, SOFTRESET).
• Object Storage: Explore your tenancy's namespaces, list storage buckets, and view bucket objects.
• Database: Monitor and list your Autonomous Databases.
• Docker Ready: Fully containerized and optimized for secure isolation.
• Extensible Architecture: Designed with modularity in mind, allowing you to easily plug in any of the hundreds of other OCI services using the official @oracle/oci-sdk.

📋 Prerequisites

Before running this MCP server, ensure you have the following set up:

1. Oracle Cloud Account: An active OCI account.
2. OCI CLI Configuration: You must have the Oracle Cloud CLI installed and configured on your machine.
   • The default location is ~/.oci/config (Linux/Mac) or C:\Users\<YourUser>\.oci\config (Windows).
   • Tip: You can set this up using the oci setup config command if you have the OCI CLI installed.
3. Node.js: Node.js 18 or higher (if running locally without Docker).
4. Docker: (Optional) If you prefer running the server in an isolated container.

🚀 Installation & Setup

Option A: Running Locally (Node.js)

1. Clone/Navigate to the repository:

   cd f:\MCP_Server\Oracle_cloud_MCP_server
   

2. Install dependencies:

   npm install
   

3. Build the TypeScript code:

   npm run build
   

4. Run the server (for testing):

   npm start
   

   Note: MCP servers communicate over stdio, so running it directly in your terminal will make it wait for JSON-RPC inputs.

Option B: Running with Docker

Running with Docker requires mounting your local ~/.oci directory into the container so the server can authenticate using your credentials.

1. Build the Docker Image:

   docker build -t oracle-cloud-mcp .
   

2. Run the Docker Container: Replace ~/.oci with the path to your OCI configuration folder.

   docker run -i -v ~/.oci:/root/.oci oracle-cloud-mcp
   

🔌 Connecting to an MCP Client

To use this server, you must configure your MCP client (such as Claude Desktop, Cline, etc.) to spawn this process.

Example: Claude Desktop Configuration

Edit your claude_desktop_config.json:

For Local Node.js Execution:

{
  "mcpServers": {
    "oracle-cloud": {
      "command": "node",
      "args": [
        "f:/MCP_Server/Oracle_cloud_MCP_server/dist/index.js"
      ]
    }
  }
}

For Docker Execution:

{
  "mcpServers": {
    "oracle-cloud": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/.oci:/root/.oci",
        "oracle-cloud-mcp"
      ]
    }
  }
}

Note: The -i flag is required for interactive standard input (stdio) communication.

🛠️ Available MCP Tools

Once connected, the LLM will have access to the following tools:

Identity Services

• oci_list_compartments: List all compartments in the tenancy. If no compartmentId is provided, it defaults to the root tenancy.
• oci_list_users: List all users within the specified compartment or the root tenancy.

Compute & Networking Services

• oci_list_instances: List all compute instances inside a specific compartmentId.
• oci_get_instance: Get detailed metadata about a specific compute instance using its instanceId.
• oci_instance_action: Execute lifecycle actions on an instance (e.g., START, STOP, SOFTRESET, RESET, SOFTSTOP).
• oci_list_vcns: List all Virtual Cloud Networks (VCNs) in a given compartmentId.

Object Storage Services

• oci_get_namespace: Fetch the Object Storage namespace associated with your tenancy.
• oci_list_buckets: List all storage buckets within a specified namespace and compartment.
• oci_list_objects: List all objects (files) inside a specific bucket.

Database Services

• oci_list_autonomous_databases: List all Autonomous Databases (ADW/ATP) within a specified compartment.

📁 Project Structure

Oracle_cloud_MCP_server/
├── src/
│   ├── index.ts                 # Main MCP server entry point and tool definitions
│   ├── auth/
│   │   └── auth.ts              # OCI Authentication module
│   └── tool/                    # Modular tool implementations
│       ├── compute/index.ts     # Compute and VCN APIs
│       ├── database/index.ts    # Autonomous Database APIs
│       ├── identity/index.ts    # Compartment and User APIs
│       └── objectstorage/index.ts # Bucket and Object APIs
├── dist/                        # Compiled JavaScript output (generated)
├── Dockerfile                   # Docker container definition
├── .dockerignore                # Excluded files for Docker build
├── .gitignore                   # Excluded files for Git tracking
├── package.json                 # Node.js dependencies and scripts
└── tsconfig.json                # TypeScript compiler configuration

🧩 Extending the Server

Because Oracle Cloud has hundreds of services, this server is designed to be easily extensible. To add a new service (e.g., oci-dns):

1. Install the SDK package:

   npm install oci-dns
   

2. Create a new tool module: Create src/tool/dns/index.ts.
3. Initialize the client: Import getAuthProvider from ../../auth/auth.js and instantiate the DNS client.
4. Export your function: Write your async function calling the OCI API.
5. Register the tool: In src/index.ts, import your new module, add a tool definition in the ListToolsRequestSchema handler, and map the tool execution in the CallToolRequestSchema switch statement.

⚠️ Troubleshooting

• Authentication Errors: If you see Failed to initialize OCI Config File Provider, ensure that the OCI CLI is installed and configured. If running via Docker, verify that you correctly mounted the ~/.oci folder using -v.
• Permission Errors: If you get a 404 or 401 error from the Oracle Cloud API, ensure the user profile configured in your ~/.oci/config file has the correct IAM policies to read compartments, instances, etc.
• No Compartment ID: Many OCI operations require a compartmentId. The root compartment OCID is usually the same as your Tenancy OCID, which is defined in your ~/.oci/config file.

Built with Model Context Protocol and the Oracle Cloud Infrastructure Node.js SDK.