Oracle MCP Server Repository

Oracle MCP Server Repository

Repository containing reference implementations of MCP (Model Context Protocol) servers for managing and interacting with Oracle products. Each MCP server under src/ may be written in a different programming language, demonstrating MCP’s language-agnostic approach.

What is MCP?

The Model Context Protocol (MCP) enables standardized, language-agnostic machine-to-machine workflows across data, models, and cloud resources. MCP servers implement specific tool suites, exposing them to MCP-compatible clients.

Project Scope

• Proof-of-concept/Reference implementations:
  This repository is not intended for production use; servers are provided as reference and for exploration, prototyping, and learning.

• Polyglot architecture:
  Each src/<server-name>/ directory represents a distinct MCP server, and these may use Python, Node.js, Java, or other languages.

Prerequisites

• Supported OS: Linux, macOS, or Windows (varies by server; check server README)
• Git (for cloning this repository)
• Internet access (for downloading dependencies)
• Cloud access: Some servers require Oracle Cloud Infrastructure (OCI) credentials and configuration (OCI docs)

Note:
Each MCP server has its own specific requirements (e.g., language runtime version, libraries).
Always see the respective src/<server>/README.md for detailed setup instructions.

Quick Start

Follow these instructions to get started as quickly as possible. Once finished, look here to set up your local development environment if you wish to contribute changes.

1. Install uv from here
2. Install python with uv python install 3.13
3. If you are using OCI servers, configure your OCI authentication
4. Choose a server below and add it to your MCP client configuration

Choose an OCI server

For most OCI users, start with oci-cloud-mcp-server. It uses the official OCI Python SDK directly, without OCI CLI subprocess calls, and is the recommended general-purpose entry point for OCI workflows.

Use oci-api-mcp-server instead when you specifically want an MCP server backed by the OCI CLI. It exposes tools for discovering and running OCI CLI commands.

Choose one of the other purpose-built servers when you already know the Oracle product or OCI domain you want to work with. These servers target specific service and product workflows rather than providing a general OCI entry point. Browse the src/ directories and read the relevant src/<server>/README.md before configuring one.

Recommended: OCI Cloud MCP Server

Run the server over stdio:

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

Then add this minimal configuration to your MCP client. Replace <profile_name> with the OCI CLI profile configured during authentication.

For macOS/Linux:

{
  "mcpServers": {
    "oracle-oci-cloud-mcp-server": {
      "command": "uvx",
      "args": [
        "oracle.oci-cloud-mcp-server@latest"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Alternative: OCI API MCP Server

Use this CLI-backed option when you specifically need OCI CLI commands:

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

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server@latest"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

To connect to an OCI MCP server running in HTTP streaming mode: Assuming you started the server by running:

ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 ORACLE_MCP_BASE_URL=http://127.0.0.1:8888 OCI_REGION=us-phoenix-1 IDCS_DOMAIN=<idcs_domain> IDCS_CLIENT_ID=<client_id> IDCS_CLIENT_SECRET=<client_secret> IDCS_AUDIENCE=<audience> uvx oracle.oci-cloud-mcp-server

Register ${ORACLE_MCP_BASE_URL}/auth/callback as a redirect URI in the OCI IAM confidential application for the server. then place the following in your MCP client configuration: :warning: NOTE: the type attribute differs across MCP clients; some use http as the transport value while others (like Cline) expect streamableHttp.

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

oracle.oci-api-mcp-server is stdio-only. For OCI HTTP servers, IDCS_REQUIRED_SCOPES is optional; if unset, the default is openid profile email oci_mcp.<server_name>.invoke, where <server_name> is the package name without oracle.oci- and -mcp-server, with - replaced by _. For example, oracle.oci-cloud-mcp-server defaults to openid profile email oci_mcp.cloud.invoke.

Running with podman

Some MCP servers in this repository support running via podman.

Installing podman

Use the following instructions to install and run podman

https://podman.io/docs/installation

Building the Container Image

You can build the container image using the following command. The command shows building the container image for the oci-api-mcp-server.

moon run oci-api-mcp-server:containerize

The above command builds the container image tagged as oracle.oci-api-mcp-server:latest.

MCP Client Configuration

For examples of configuring MCP clients to run the server using podman, see the client-specific sections below. Configurations typically involve using podman run as the command, with appropriate flags and volume mounts for credentials if needed (e.g., mounting ~/.oci for OCI servers running over stdio transport).

Alternatively, if you want to use HTTP transport using the podman container, then start an OCI HTTP-capable MCP server using the following command and configure your client as mentioned in Quickstart section above.

podman run -e ORACLE_MCP_HOST=0.0.0.0 -e ORACLE_MCP_PORT=8888 -e ORACLE_MCP_BASE_URL=http://127.0.0.1:8888 -e OCI_REGION=us-phoenix-1 -e IDCS_DOMAIN=<idcs_domain> -e IDCS_CLIENT_ID=<client_id> -e IDCS_CLIENT_SECRET=<client_secret> -e IDCS_AUDIENCE=<audience> -p 127.0.0.1:8888:8888 oracle.oci-cloud-mcp-server:latest

For local development, keep -p 127.0.0.1:8888:8888. Changing it to -p 8888:8888 exposes the server beyond localhost.

Authentication

For OCI MCP servers running over stdio transport:

1. Install the OCI CLI
2. Configure your OCI CLI profile

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

where: <region> is the region you would like to authenticate in (e.g. us-phoenix-1) <tenancy_name> is the name of your OCI tenancy

Some MCP servers may not work with token-based authentication alone. See more about API key-based authentication here.

All stdio actions are performed with the permissions of the configured OCI CLI profile. We advise least-privilege IAM setup, secure credential management, safe network practices, secure logging, and warn against exposing secrets.

Remember to refresh the session once it expires with:

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

<profile_name> is the profile that you set up in the steps above. You can view a list of your profiles by running cat ~/.oci/config on macOS/Linux if you forget which profile you have set up.

For OCI MCP servers running over HTTP transport, use an OCI IAM confidential application and set IDCS_DOMAIN, IDCS_CLIENT_ID, IDCS_CLIENT_SECRET, IDCS_AUDIENCE, ORACLE_MCP_BASE_URL, ORACLE_MCP_HOST, ORACLE_MCP_PORT, and OCI_REGION. Register ${ORACLE_MCP_BASE_URL}/auth/callback as a redirect URI in that application. HTTP requests run as the authenticated OCI IAM user and do not use the local OCI CLI profile for request authentication. IDCS_REQUIRED_SCOPES is optional; if unset, the server defaults to openid profile email oci_mcp.<server_name>.invoke. Create and grant that custom scope in your confidential application, or override it with IDCS_REQUIRED_SCOPES.

For server authors, the shared library keeps credential resolution and HTTP token exchange consistent while each server retains its listener, service client lifecycle, and derived user agent. See the shared authentication module for the full configuration matrix and the HTTP IDCS authentication section for the provider and per-request token-exchange API. HTTP-derived OCI clients must be treated as caller-specific and must not be reused across callers.

Client configuration

Each MCP server exposes endpoints that your client can connect to. To enable this connection, just add the relevant server to your MCP client’s configuration file. You can find the list of servers under the src folder.

Refer to the sections below for client-specific configuration instructions.

Cline

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server@latest"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "podman",
      "args": ["run", "-i", "--rm", "-v", "/path/to/your/.oci:/app/.oci", "oracle.oci-api-mcp-server:latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

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

MCPHost

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "OCI_CONFIG_PROFILE": "<profile_name>",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

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

Local development

Install proto and run proto install from the repository root before using Moon. For a Python server, run its tests with Moon and launch its source checkout directly with uv:

moon run oci-api-mcp-server:test
uv --directory src/oci-api-mcp-server run --locked oracle.oci-api-mcp-server

uv run creates and updates the server project's own .venv from its lockfile. The API server's common dependency resolves to this repository's src/common. Build a distribution only when you need to check packaging, with moon run oci-api-mcp-server:build.

To load this checkout in an MCP client, use the absolute path to the server project. For example:

{
  "mcpServers": {
    "oracle-oci-api-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<absolute path to this repo>/src/oci-api-mcp-server",
        "run",
        "--locked",
        "oracle.oci-api-mcp-server"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

For other servers, use their project directory and the executable declared in their pyproject.toml. For Node.js, Java, or other runtimes, follow the server's README.

JavaScript MCP servers

Most servers in this repository are Python packages managed with uv. JavaScript servers are first-class MCP servers too, but they use npm and are intentionally excluded from the Python package loop.

The OCI JavaScript MCP server lives in src/oci-javascript-mcp-server:

moon run oci-javascript-mcp-server:test
moon run oci-javascript-mcp-server:check
moon run oci-javascript-mcp-server:build

Directory Structure

.
├── src/
│   ├── oci-api-mcp-server/        # MCP server (Python package)
│   ├── oci-javascript-mcp-server/ # MCP server (Node.js package)
│   ├── oracle-db-mcp-java-toolkit/ # MCP server (Java package)
│   └── ...
├── LICENSE.txt
├── README.md
├── CONTRIBUTING.md
└── SECURITY.md

Each server subdirectory includes its own README.md with language/runtime details, installation, and usage.

Testing

Testing with a Local Development MCP Server

Use the local development MCP client configuration above to launch the checkout. Changes to Python source are available on the next server start; no build or installation into a shared environment is needed.

To test an HTTP-capable server locally:

moon run oci-api-mcp-server:test

then start the server:

ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 \
  uv --directory src/oci-api-mcp-server run --locked oracle.oci-api-mcp-server

Inspector

The Model Context Protocol (MCP) provides Inspector which is a developer tool for testing and debugging MCP servers. More information on Inspector can be found in the documentation.

The Inspector runs directly through npx without requiring installation. For instance, to inspect your locally developed server, you can run:

npx @modelcontextprotocol/inspector \
  uv \
  --directory "<absolute path to this repo>/src/oci-api-mcp-server" \
  run \
  --locked \
  oracle.oci-api-mcp-server

Inspector will run your server on localhost (for instance: http://127.0.0.1:6274) which should automatically open the tool for debugging and development.

Running tests

moon run :lint :lock-check :install-check :test :check :build
moon run root:combine-coverage

CI uses moon ci with the same validation targets to run only tasks affected by the changed files and their dependencies. Pull requests compare the checked-out merge commit with the base commit; pushes compare with the previous commit. Python coverage is combined and uploaded only when Python tests produce coverage files. Changes to shared toolchain and CI configuration select all validation tasks. Project Moon configuration changes select that project's validation tasks.

Running tasks with moon

The standard Python server projects and the JavaScript MCP server are orchestrated with moon. Tool versions are pinned in .prototools; after installing proto, install the pinned tools and run tasks from the repository root:

proto install
moon run oci-compute-mcp-server:test
moon run oci-javascript-mcp-server:test
moon run root:lint
moon run :build

Moon uses each project's language-specific package definition: pyproject.toml and uv.lock for Python, and package.json and package-lock.json for JavaScript. Build, test, and publish tasks are defined in Moon. Other projects excluded from Moon continue to use the validation commands in their own README. Use uv lock or uv sync from a Python project's directory when updating or syncing that project's dependencies.

Optional end-to-end tests can be run with moon run root:e2e-tests after following the setup in tests/README.md. Python container images with a Containerfile can be built with moon run <project>:containerize.

Publishing

Use the manually dispatched Publish package workflow from main. Select pypi or testpypi with a Python Moon project ID or all-python to release every Moon-managed Python package. Select npm with oci-javascript-mcp-server for the JavaScript package. Moon runs checks and build before the workflow passes the distributions to its publish job. Releasing a Python server publishes oracle-mcp-common first and waits for it to appear on the selected index. Ordinary CI never invokes the publish tasks.

Configure the pypi, testpypi, and npm GitHub environments with release approval rules and their respective PYPI_TOKEN, TEST_PYPI_TOKEN, and NPM_TOKEN secrets before running the workflow. The publish job reads only the secret for its selected registry. The Moon publish tasks require the release workflow's RELEASE_PUBLISH flag, and Python publishing also requires an explicit upload and check URL.

To verify a Test PyPI package after publishing:

uvx --refresh-package oracle.oci-api-mcp-server \
  --index https://test.pypi.org/simple \
  --from 'oracle.oci-api-mcp-server==<published-version>' \
  oracle.oci-api-mcp-server

Replace <published-version> with the version you released.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.

Security

Please consult the security guide for our responsible security vulnerability disclosure process.

License

Copyright (c) 2025 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at
https://oss.oracle.com/licenses/upl/.

Third-Party APIs

Developers choosing to distribute a binary implementation of this project are responsible for obtaining and providing all required licenses and copyright notices for the third-party code used in order to ensure compliance with their respective open source licenses.

Disclaimer

Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.