# 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:**
   ```bash
   cd f:\MCP_Server\Oracle_cloud_MCP_server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the TypeScript code:**
   ```bash
   npm run build
   ```

4. **Run the server (for testing):**
   ```bash
   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:**
   ```bash
   docker build -t oracle-cloud-mcp .
   ```

2. **Run the Docker Container:**
   Replace `~/.oci` with the path to your OCI configuration folder.
   ```bash
   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:
```json
{
  "mcpServers": {
    "oracle-cloud": {
      "command": "node",
      "args": [
        "f:/MCP_Server/Oracle_cloud_MCP_server/dist/index.js"
      ]
    }
  }
}
```

#### For Docker Execution:
```json
{
  "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

```text
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**:
   ```bash
   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](https://modelcontextprotocol.io/) and the [Oracle Cloud Infrastructure Node.js SDK](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/typescriptsdk.htm).*