Installation

This guide covers all installation methods for Oracle MCP Servers, including prerequisites, platform-specific instructions, and container deployments.

Prerequisites

System Requirements

Operating System

Linux (Ubuntu, RHEL, etc.)
macOS (10.15+)
Windows (10/11)

Core Tools

Git (for cloning repository)
Internet access
Terminal/Command Prompt

Language Runtimes

Python 3.13+ (most servers)
Node.js 18+ (some servers)
Java 21+ (Java-based servers)

Each MCP server may have specific requirements. Always check the server’s individual README in src/<server-name>/ for detailed prerequisites.

Required Tools

uv (Python Package Manager)

The uv tool is the recommended way to install and run Python-based Oracle MCP servers.

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify installation:

uv --version

For alternative installation methods, see the official uv documentation.

Python 3.13

Install Python 3.13 using uv:

uv python install 3.13

Verify the installation:

uv python list

OCI Authentication

Most Oracle Cloud Infrastructure (OCI) MCP servers require authentication with your Oracle Cloud account. There are two primary authentication methods:

Method 1: Session Token Authentication (Recommended)

Install OCI CLI

Follow the official OCI CLI installation guide for your platform.

brew install oci-cli

Verify installation:

oci --version

Authenticate with session tokens

Run the authentication command:

oci session authenticate --region=<region> --tenancy-name=<tenancy_name>

Replace:

<region>: Your OCI region (e.g., us-phoenix-1, us-ashburn-1, eu-frankfurt-1)
<tenancy_name>: Your OCI tenancy name

Example:

oci session authenticate --region=us-phoenix-1 --tenancy-name=mycompany

This will:

Open a browser for authentication
Create a session token
Store credentials in ~/.oci/config

Verify authentication

Test your authentication:

oci session validate

List your configured profiles:

cat ~/.oci/config

Refresh expired sessions

Session tokens expire after a certain period. Refresh them with:

oci session authenticate --profile-name <profile_name> --region <region> --auth security_token

Example:

oci session authenticate --profile-name DEFAULT --region us-phoenix-1 --auth security_token

Method 2: API Key Authentication

Some MCP servers may not work with token-based authentication alone. For API key-based authentication:

Generate an API signing key pair following the OCI documentation
Upload the public key to your OCI user settings
Configure your ~/.oci/config file with the key path

For detailed instructions, see OCI SDK configuration documentation.

All actions are performed with the permissions of your configured OCI CLI profile. We strongly recommend:

Using least-privilege IAM policies
Secure credential management
Never exposing secrets in logs or configuration files
Regular credential rotation

Installation Methods

Method 1: Quick Install with uvx (Recommended)

The fastest way to use Oracle MCP servers without local development:

Choose your server

Available Python-based servers include:

oracle.oci-api-mcp-server - Generic OCI CLI command execution
oracle.oci-compute-mcp-server - Compute instance management
oracle.oci-database-mcp-server - Database service management
oracle.oci-identity-mcp-server - Identity and access management
oracle.oci-networking-mcp-server - Virtual network management
oracle.dbtools-mcp-server - Database tools and SQL execution
oracle.mysql-mcp-server - MySQL and HeatWave integration
And 15+ more servers

Run the server

Use uvx to run the server directly without installation:

uvx oracle.oci-api-mcp-server@latest

The @latest suffix ensures you always use the most recent version. You can also specify a version like @1.1.4.

Configure your MCP client

Add the server to your MCP client configuration (see Quickstart for examples).

Method 2: Local Development Installation

For contributing changes or customizing servers:

Clone the repository

git clone https://github.com/oracle/oracle-mcp-servers.git
cd oracle-mcp-servers

Set up Python virtual environment

uv venv --python 3.13 --seed
source .venv/bin/activate
uv pip install -r requirements-dev.txt

Build and install servers

make build
make install

This builds all Python-based servers and installs them in your virtual environment.

Configure MCP client for local development

Update your MCP client configuration to use the local installation:

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "VIRTUAL_ENV": "/absolute/path/to/oracle-mcp-servers/.venv",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Replace /absolute/path/to/oracle-mcp-servers/.venv with the actual absolute path to your cloned repository’s virtual environment.

Method 3: Container Deployment

Run MCP servers using Podman (or Docker) containers for isolation and portability.

Install Podman

Follow the official Podman installation guide:

brew install podman
podman machine init
podman machine start

Verify installation:

podman --version

Build the container image

Clone the repository and build a specific server:

git clone https://github.com/oracle/oracle-mcp-servers.git
cd oracle-mcp-servers
SUBDIRS=src/oci-api-mcp-server make containerize

This builds an image tagged as oracle.oci-api-mcp-server:latest.

You can build other servers by changing the SUBDIRS value (e.g., src/oci-compute-mcp-server).

Run with STDIO transport

Configure your MCP client to run the containerized server:

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/username/.oci:/app/.oci",
        "oracle.oci-api-mcp-server:latest"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Replace /Users/username/.oci or C:\\Users\\username\\.oci with the actual path to your OCI configuration directory.

Run with HTTP transport (optional)

Start the server with HTTP transport:

podman run \
  -v "$HOME/.oci:/app/.oci" \
  -e ORACLE_MCP_HOST=0.0.0.0 \
  -e ORACLE_MCP_PORT=8888 \
  -p 8888:8888 \
  oracle.oci-api-mcp-server:latest

Then configure your client for HTTP connection:

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8888/mcp"
    }
  }
}

Container path resolution

When using containers, ensure file paths in your ~/.oci/config use the ~ character so paths resolve correctly both inside and outside the container:

[DEFAULT]
user=ocid1.user.oc1..
fingerprint=aa:bb:cc:dd:ee:ff
tenancy=ocid1.tenancy.oc1..
region=us-phoenix-1
key_file=~/.oci/oci_api_key.pem
security_token_file=~/.oci/sessions/DEFAULT/token

Avoid absolute paths like /Users/username/.oci/oci_api_key.pem.

Platform-Specific Notes

macOS

Use Homebrew for installing tools when possible: brew install oci-cli podman
Ensure command-line tools are installed: xcode-select --install
Podman requires a virtual machine: podman machine init && podman machine start

Linux

Most distributions work out of the box
Ensure you have appropriate permissions for Docker/Podman (add user to docker group if needed)
For rootless Podman, follow rootless setup guide

Windows

Use PowerShell (not Command Prompt) for better compatibility
Windows Subsystem for Linux (WSL2) is recommended for the best experience
Ensure execution policies allow running scripts: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Use forward slashes or escaped backslashes in JSON paths

Verifying Installation

After installation, verify everything is working:

Check uv installation

uv --version
uv python list

Check OCI CLI

oci --version
oci session validate

Test a server directly

Run a server in test mode:

uvx oracle.oci-api-mcp-server --help

Use MCP Inspector (optional)

The MCP Inspector is a developer tool for testing servers:

npx @modelcontextprotocol/inspector uvx oracle.oci-api-mcp-server

This opens a web interface (usually http://127.0.0.1:6274) for testing server capabilities.

Environment Variables

Common environment variables for Oracle MCP servers:

Variable	Description	Default	Example
`OCI_CONFIG_PROFILE`	OCI CLI profile to use	`DEFAULT`	`PRODUCTION`
`FASTMCP_LOG_LEVEL`	Logging verbosity	`INFO`	`ERROR`, `DEBUG`
`ORACLE_MCP_HOST`	HTTP server host	-	`127.0.0.1`
`ORACLE_MCP_PORT`	HTTP server port	-	`8888`
`VIRTUAL_ENV`	Path to Python virtual environment	-	`/path/to/.venv`

Server-specific environment variables are documented in each server’s README.

Troubleshooting

uv command not found

Ensure uv is in your PATH
Restart your terminal after installation
On macOS/Linux, add to PATH: export PATH="$HOME/.cargo/bin:$PATH"
On Windows, the installer should add to PATH automatically

Python version errors

Check available Python versions: uv python list
Install required version: uv python install 3.13
Some servers may work with Python 3.11+ (check server README)

OCI authentication failures

Verify session is valid: oci session validate
Check config file exists: cat ~/.oci/config
Refresh session token: oci session authenticate --profile-name DEFAULT --region <region> --auth security_token
For API key auth, verify key file path and permissions

Container permission errors

On Linux, check SELinux context for mounted volumes
Use :Z suffix for volume mounts: -v ~/.oci:/app/.oci:Z
Verify file permissions: ls -la ~/.oci
For rootless Podman, ensure proper UID mapping

Windows path issues

Use forward slashes or escaped backslashes in JSON
Correct: "C:\\Users\\username\\.oci" or "C:/Users/username/.oci"
Incorrect: "C:\Users\username\.oci"
Consider using WSL2 for better compatibility

Next Steps

Quickstart Guide

Get your first MCP server running in minutes

Server Overview

Explore all 22 available Oracle MCP servers

Client Configuration

Detailed setup for Cline, Cursor, and other clients

Development Setup

Set up a local development environment

Get Started

Core Concepts

Client Configuration

Deployment

Prerequisites

System Requirements

Operating System

Core Tools

Language Runtimes

Required Tools

uv (Python Package Manager)

Python 3.13

OCI Authentication

Method 1: Session Token Authentication (Recommended)

Method 2: API Key Authentication

Installation Methods

Method 1: Quick Install with uvx (Recommended)

Method 2: Local Development Installation

Method 3: Container Deployment

Platform-Specific Notes

macOS

Linux

Windows

Verifying Installation

Environment Variables

Troubleshooting

Next Steps

Quickstart Guide

Server Overview

Client Configuration

Development Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Client Configuration

Deployment

​Prerequisites

​System Requirements

Operating System

Core Tools

Language Runtimes

​Required Tools

​uv (Python Package Manager)

​Python 3.13

​OCI Authentication

​Method 1: Session Token Authentication (Recommended)

​Method 2: API Key Authentication

​Installation Methods

​Method 1: Quick Install with uvx (Recommended)

​Method 2: Local Development Installation

​Method 3: Container Deployment

​Platform-Specific Notes

​macOS

​Linux

​Windows

​Verifying Installation

​Environment Variables

​Troubleshooting

​Next Steps

Quickstart Guide

Server Overview

Client Configuration

Development Setup

Build docs developers (and LLMs) love

Prerequisites

System Requirements

Required Tools

uv (Python Package Manager)

Python 3.13

OCI Authentication

Method 1: Session Token Authentication (Recommended)

Method 2: API Key Authentication

Installation Methods

Method 1: Quick Install with uvx (Recommended)

Method 2: Local Development Installation

Method 3: Container Deployment

Platform-Specific Notes

macOS

Linux

Windows

Verifying Installation

Environment Variables

Troubleshooting

Next Steps