Content
# 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).*
