Skip to content
Back to search

mcp

Repository containing MCP (Model Context Protocol) servers that provides a suite of tools for managing and interacting with Oracle products.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oracle/mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oracle/mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oracle--mcp/badge.svg)](/listings/oracle--mcp)

HTML

<a href="/listings/oracle--mcp"><img src="/api/listings/oracle--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Follow these instructions to get started as quickly as possible. Once finished, look [here](#local-development) to set up your local development environment if you wish to [contribute](#contributing) changes.

1. Install `uv` from [here](https://docs.astral.sh/uv/getting-started/installation/) 2. Install python with `uv python install 3.13` 3. If you are using OCI servers, configure your [OCI authentication](#authentication) 4. Choose a server below and add it to your [MCP client configuration](#client-configuration)

Choose an OCI server

For most OCI users, start with [`oci-cloud-mcp-server`](src/oci-cloud-mcp-server/README.md). 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`](src/oci-api-mcp-server/README.md) 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/`](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](#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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 621 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Oracle MCP Server Repository
  2. 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.
  3. ## What is MCP?
  4. 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.
  5. ## Project Scope
  6. - **Proof-of-concept/Reference implementations:**
  7. This repository is not intended for production use; servers are provided as reference and for exploration, prototyping, and learning.
  8. - **Polyglot architecture:**
  9. Each `src/<server-name>/` directory represents a distinct MCP server, and these may use Python, Node.js, Java, or other languages.
  10. ## Prerequisites
  11. - Supported OS: Linux, macOS, or Windows (varies by server; check server README)
  12. - Git (for cloning this repository)
  13. - Internet access (for downloading dependencies)
  14. - *Cloud access*: Some servers require Oracle Cloud Infrastructure (OCI) credentials and configuration ([OCI docs](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm))
  15. **Note:**
  16. Each MCP server has its own specific requirements (e.g., language runtime version, libraries).
  17. Always see the respective `src/<server>/README.md` for detailed setup instructions.
  18. ## Quick Start
  19. Follow these instructions to get started as quickly as possible. Once finished, look [here](#local-development) to set up your local development environment if you wish to [contribute](#contributing) changes.
  20. 1. Install `uv` from [here](https://docs.astral.sh/uv/getting-started/installation/)
  21. 2. Install python with `uv python install 3.13`
  22. 3. If you are using OCI servers, configure your [OCI authentication](#authentication)
  23. 4. Choose a server below and add it to your [MCP client configuration](#client-configuration)
  24. ### Choose an OCI server
  25. For most OCI users, start with [`oci-cloud-mcp-server`](src/oci-cloud-mcp-server/README.md). It uses the official OCI Python SDK directly, without OCI CLI subprocess calls, and is the recommended general-purpose entry point for OCI workflows.
  26. Use [`oci-api-mcp-server`](src/oci-api-mcp-server/README.md) instead when you specifically want an MCP server backed by the OCI CLI. It exposes tools for discovering and running OCI CLI commands.
  27. 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/`](src/) directories and read the relevant `src/<server>/README.md` before configuring one.
  28. ### Recommended: OCI Cloud MCP Server
  29. Run the server over stdio:
  30. ```sh
  31. uvx oracle.oci-cloud-mcp-server@latest
  32. ```
  33. Then add this minimal configuration to your MCP client. Replace `<profile_name>` with the OCI CLI profile configured during [authentication](#authentication).
  34. For macOS/Linux:
  35. ```json
  36. {
  37. "mcpServers": {
  38. "oracle-oci-cloud-mcp-server": {
  39. "command": "uvx",
  40. "args": [
  41. "oracle.oci-cloud-mcp-server@latest"
  42. ],
  43. "env": {
  44. "OCI_CONFIG_PROFILE": "<profile_name>",
  45. "FASTMCP_LOG_LEVEL": "ERROR"
  46. }
  47. }
  48. }
  49. }
  50. ```
  51. ### Alternative: OCI API MCP Server
  52. Use this CLI-backed option when you specifically need OCI CLI commands:
  53. ```sh
  54. uvx oracle.oci-api-mcp-server@latest
  55. ```
  56. ```json
  57. {
  58. "mcpServers": {
  59. "oracle-oci-api-mcp-server": {
  60. "command": "uvx",
  61. "args": [
  62. "oracle.oci-api-mcp-server@latest"
  63. ],
  64. "env": {
  65. "OCI_CONFIG_PROFILE": "<profile_name>",
  66. "FASTMCP_LOG_LEVEL": "ERROR"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. To connect to an OCI MCP server running in HTTP streaming mode:
  73. Assuming you started the server by running:
  74. ```bash
  75. 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
  76. ```
  77. Register `${ORACLE_MCP_BASE_URL}/auth/callback` as a redirect URI in the OCI IAM confidential application for the server.
  78. then place the following in your MCP client configuration:
  79. :warning: NOTE: the `type` attribute differs across MCP clients; some use `http` as the
  80. transport value while others (like Cline) expect `streamableHttp`.
  81. ```json
  82. {
  83. "mcpServers": {
  84. "oracle-oci-cloud-mcp-server": {
  85. "type": "streamableHttp",
  86. "url": "http://127.0.0.1:8888/mcp"
  87. }
  88. }
  89. }
  90. ```
  91. `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`.
  92. ## Running with podman
  93. Some MCP servers in this repository support running via podman.
  94. ### Installing podman
  95. Use the following instructions to install and run podman
  96. https://podman.io/docs/installation
  97. ### Building the Container Image
  98. You can build the container image using the following command. The command shows building the container image for the oci-api-mcp-server.
  99. ```sh
  100. moon run oci-api-mcp-server:containerize
  101. ```
  102. The above command builds the container image tagged as `oracle.oci-api-mcp-server:latest`.
  103. ### MCP Client Configuration
  104. 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).
  105. 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.
  106. ```bash
  107. 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
  108. ```
  109. For local development, keep `-p 127.0.0.1:8888:8888`. Changing it to `-p 8888:8888` exposes the server beyond localhost.
  110. ## Authentication
  111. For OCI MCP servers running over stdio transport:
  112. 1. Install the [OCI CLI](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm)
  113. 2. Configure your OCI CLI profile
  114. ```bash
  115. oci session authenticate --region=<region> --tenancy-name=<tenancy_name>
  116. ```
  117. where:
  118. `<region>` is the region you would like to authenticate in (e.g. `us-phoenix-1`)
  119. `<tenancy_name>` is the name of your OCI tenancy
  120. Some MCP servers may not work with token-based authentication alone. See more about API key-based authentication [here](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm).
  121. 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.
  122. Remember to refresh the session once it expires with:
  123. ```bash
  124. oci session authenticate --profile-name <profile_name> --region <region> --auth security_token
  125. ```
  126. `<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.
  127. 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`.
  128. For server authors, the shared library keeps credential resolution and HTTP
  129. token exchange consistent while each server retains its listener, service
  130. client lifecycle, and derived user agent. See the [shared authentication
  131. module](src/common/README.md#authentication-module) for the full configuration
  132. matrix and the [HTTP IDCS authentication section](src/common/README.md#http-idcs-authentication)
  133. for the provider and per-request token-exchange API. HTTP-derived OCI clients
  134. must be treated as caller-specific and must not be reused across callers.
  135. ## Client configuration
  136. 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.
  137. Refer to the sections below for client-specific configuration instructions.
  138. ### Cline
  139. <details>
  140. <summary>Setup</summary>
  141. Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
  142. 1. If using Visual Studio Code, install the [Cline VS Code Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) (or equivalent extension for your preferred IDE).
  143. 2. Once installed, click the extension to open it.
  144. 3. Click the **MCP Servers** button near the top of the the extension's panel.
  145. 4. Select the **Installed** tab.
  146. 5. Click **Configure MCP Servers** to open the `cline_mcp_settings.json` file.
  147. 6. In the `cline_mcp_settings.json` file, add your desired MCP servers in the `mcpServers` object. Below is an example for for the generic OCI API MCP server. Make sure to save the file after editing. `<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
  148. For macOS/Linux:
  149. ```json
  150. {
  151. "mcpServers": {
  152. "oracle-oci-api-mcp-server": {
  153. "type": "stdio",
  154. "command": "uvx",
  155. "args": [
  156. "oracle.oci-api-mcp-server@latest"
  157. ],
  158. "env": {
  159. "OCI_CONFIG_PROFILE": "<profile_name>",
  160. "FASTMCP_LOG_LEVEL": "ERROR"
  161. }
  162. }
  163. }
  164. }
  165. ```
  166. Alternatively, to run using podman (example for oracle.oci-api-mcp-server):
  167. ```json
  168. {
  169. "mcpServers": {
  170. "oracle-oci-api-mcp-server": {
  171. "autoApprove": [],
  172. "disabled": false,
  173. "timeout": 60,
  174. "type": "stdio",
  175. "command": "podman",
  176. "args": ["run", "-i", "--rm", "-v", "/path/to/your/.oci:/app/.oci", "oracle.oci-api-mcp-server:latest"],
  177. "env": {
  178. "FASTMCP_LOG_LEVEL": "INFO"
  179. }
  180. }
  181. }
  182. }
  183. ```
  184. Replace `"/path/to/your/.oci"` with the actual path to your OCI configuration directory.
  185. ⚠️ **NOTE**: Ensure that the _key_file_ field in /path/to/your/.oci/config uses the ~ character so that the path resolves both inside and outside the container; for example: `key_file=~/.oci/oci_api_key.pem`.
  186. For servers not requiring OCI credentials, omit the `-v` volume mount.
  187. For Windows - **TODO**
  188. 7. Once installed, you should see a list of your **MCP Servers** under the **Installed** tab. They will have a green toggle that shows that they are enabled.
  189. 8. Click **Done** when finished.
  190. </details>
  191. ### Cursor
  192. <details>
  193. <summary>Setup</summary>
  194. Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
  195. 1. You can place MCP configurations in two locations, depending on your use case:
  196. **Project Configuration**: For tools specific to a project, create a `.cursor/mcp.json` file in your project directory. This allows you to define MCP servers that are only available within that specific project.
  197. **Global Configuration**: For tools that you want to use across all projects, create a `~/.cursor/mcp.json` file in your home directory. This makes MCP servers available in all your Cursor workspaces.
  198. **`.cursor/mcp.json`**
  199. For macOS/Linux:
  200. ```json
  201. {
  202. "mcpServers": {
  203. "oracle-oci-api-mcp-server": {
  204. "type": "stdio",
  205. "command": "uvx",
  206. "args": [
  207. "oracle.oci-api-mcp-server"
  208. ],
  209. "env": {
  210. "OCI_CONFIG_PROFILE": "<profile_name>",
  211. "FASTMCP_LOG_LEVEL": "ERROR"
  212. }
  213. }
  214. }
  215. }
  216. ```
  217. Alternatively, to run using podman (example for oracle-oci-api-mcp-server):
  218. ```json
  219. {
  220. "mcpServers": {
  221. "oracle-oci-api-mcp-server": {
  222. "type": "stdio",
  223. "command": "podman",
  224. "args": ["run", "-i", "--rm", "-v", "/path/to/your/.oci:/app/.oci", "oracle.oci-api-mcp-server:latest"],
  225. "env": {
  226. "FASTMCP_LOG_LEVEL": "INFO"
  227. }
  228. }
  229. }
  230. }
  231. ```
  232. Replace `"/path/to/your/.oci"` with the actual path to your OCI configuration directory.
  233. For servers not requiring OCI credentials, omit the `-v` volume mount.
  234. `<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
  235. For Windows - **TODO**
  236. 2. In your **Cursor Settings**, check your **Installed Servers** under the **MCP** tab to ensure that your `.cursor/mcp.json` was properly configured.
  237. </details>
  238. ### MCPHost
  239. <details>
  240. <summary>Setup</summary>
  241. Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
  242. 1. Download [Ollama](https://ollama.com/download)
  243. 2. Start the Ollama server
  244. For macOS: If installed via the official installer, `ollama start`. If installed via homebrew, `brew services start ollama`
  245. For Windows: If installed via the official installer, the server is typically configured to start automatically in the background and on system boot.
  246. For Linux: `sudo systemctl start ollama`
  247. 3. Verify the ollama server has started with `curl http://localhost:11434`. A successful response will typically be "Ollama is running".
  248. 4. Fetch the large language model, where `<model>` is the name of your desired model (e.g. `llama3.2`), with `ollama pull <model>`. For more options, check Ollama's list of [models that support tool calling](https://ollama.com/search?c=tools).
  249. 5. Install `go` from [here](https://go.dev/doc/install)
  250. 6. Install `mcphost` with `go install github.com/mark3labs/mcphost@latest`
  251. 7. Add go's bin to your PATH with `export PATH=$PATH:~/go/bin`
  252. 8. Create an mcphost configuration file (e.g. `~/.mcphost.json`). Check [here](https://github.com/mark3labs/mcphost?tab=readme-ov-file#mcp-servers) for more info.
  253. 9. Add your desired server to the `mcpServers` object. Below is an example for for the compute OCI MCP server. Make sure to save the file after editing.
  254. For macOS/Linux:
  255. ```json
  256. {
  257. "mcpServers": {
  258. "oracle-oci-api-mcp-server": {
  259. "type": "stdio",
  260. "command": "uvx",
  261. "args": [
  262. "oracle.oci-api-mcp-server"
  263. ],
  264. "env": {
  265. "OCI_CONFIG_PROFILE": "<profile_name>",
  266. "FASTMCP_LOG_LEVEL": "ERROR"
  267. }
  268. }
  269. }
  270. }
  271. ```
  272. Alternatively, to run using podman (example for oracle-oci-api-mcp-server):
  273. ```json
  274. {
  275. "mcpServers": {
  276. "oracle-oci-api-mcp-server": {
  277. "type": "stdio",
  278. "command": "podman",
  279. "args": ["run", "-i", "--rm", "-v", "/path/to/your/.oci:/app/.oci", "oracle.oci-api-mcp-server:latest"],
  280. "env": {
  281. "FASTMCP_LOG_LEVEL": "INFO"
  282. }
  283. }
  284. }
  285. }
  286. ```
  287. Replace `"/path/to/your/.oci"` with the actual path to your OCI configuration directory.
  288. For servers not requiring OCI credentials, omit the `-v` volume mount.
  289. `<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
  290. For Windows - **TODO**
  291. 10. Start `mcphost` with `OCI_CONFIG_PROFILE=<profile> mcphost -m ollama:<model> --config <config-path>`
  292. 1. `<model>` is the model you chose above
  293. 2. `<profile>` is the name of the OCI CLI profile that you set up above
  294. 3. `<config-path>` is the path to the mcphost configuration json file that you made above
  295. </details>
  296. ## Local development
  297. On macOS, install proto with [Homebrew](https://formulae.brew.sh/formula/proto)
  298. using `brew install proto`, then run `proto setup` and open a new terminal.
  299. For other platforms, see the [proto installation guide](https://moonrepo.dev/docs/proto/install).
  300. From the repository root, run `proto install moon --immutable-lockfile` and
  301. `moon setup`. See [Running tasks with moon](#running-tasks-with-moon) for
  302. platform setup. For a Python server, run its tests with Moon and launch its
  303. source checkout directly with `uv`:
  304. ```sh
  305. moon run oci-api-mcp-server:test
  306. uv --directory src/oci-api-mcp-server run --locked oracle.oci-api-mcp-server
  307. ```
  308. `uv run` creates and updates the server project's own `.venv` from its lockfile.
  309. The Common consumers resolve `oracle-mcp-common` to this repository's `src/common`
  310. through `[tool.uv.sources]` entries with `workspace = true`. Moon infers their
  311. project dependencies from these declarations so Common changes trigger consumer
  312. tests and lock checks.
  313. Build a distribution only when you need to check packaging, with
  314. `moon run oci-api-mcp-server:build`.
  315. To load this checkout in an MCP client, use the absolute path to the server
  316. project. For example:
  317. ```json
  318. {
  319. "mcpServers": {
  320. "oracle-oci-api-mcp-server": {
  321. "command": "uv",
  322. "args": [
  323. "--directory",
  324. "<absolute path to this repo>/src/oci-api-mcp-server",
  325. "run",
  326. "--locked",
  327. "oracle.oci-api-mcp-server"
  328. ],
  329. "env": {
  330. "FASTMCP_LOG_LEVEL": "ERROR"
  331. }
  332. }
  333. }
  334. }
  335. ```
  336. For other servers, use their project directory and the executable declared in
  337. their `pyproject.toml`. For Node.js, Java, or other runtimes, follow the server's
  338. README.
  339. ### JavaScript MCP servers
  340. 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.
  341. The OCI JavaScript MCP server lives in `src/oci-javascript-mcp-server`:
  342. ```sh
  343. moon run oci-javascript-mcp-server:test
  344. moon run oci-javascript-mcp-server:check
  345. moon run oci-javascript-mcp-server:build
  346. ```
  347. ## Directory Structure
  348. ```
  349. .
  350. ├── src/
  351. │ ├── oci-api-mcp-server/ # MCP server (Python package)
  352. │ ├── oci-javascript-mcp-server/ # MCP server (Node.js package)
  353. │ ├── oracle-db-mcp-java-toolkit/ # MCP server (Java package)
  354. │ └── ...
  355. ├── LICENSE.txt
  356. ├── README.md
  357. ├── CONTRIBUTING.md
  358. └── SECURITY.md
  359. ```
  360. Each server subdirectory includes its own `README.md` with language/runtime details, installation, and usage.
  361. ## Testing
  362. ### Testing with a Local Development MCP Server
  363. Use the [local development MCP client configuration](#local-development) above
  364. to launch the checkout. Changes to Python source are available on the next
  365. server start; no build or installation into a shared environment is needed.
  366. To test an HTTP-capable server locally:
  367. ```bash
  368. moon run oci-api-mcp-server:test
  369. ```
  370. then start the server:
  371. ```bash
  372. ORACLE_MCP_HOST=127.0.0.1 ORACLE_MCP_PORT=8888 \
  373. uv --directory src/oci-api-mcp-server run --locked oracle.oci-api-mcp-server
  374. ```
  375. ### Inspector
  376. The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
  377. provides [Inspector](https://github.com/modelcontextprotocol/inspector) which is a developer tool for testing and
  378. debugging MCP servers. More information on Inspector can be found in
  379. the [documentation](https://modelcontextprotocol.io/docs/tools/inspector).
  380. The Inspector runs directly through npx without requiring installation. For instance, to inspect your locally developed
  381. server, you can run:
  382. ```sh
  383. npx @modelcontextprotocol/inspector \
  384. uv \
  385. --directory "<absolute path to this repo>/src/oci-api-mcp-server" \
  386. run \
  387. --locked \
  388. oracle.oci-api-mcp-server
  389. ```
  390. Inspector will run your server on localhost (for instance: http://127.0.0.1:6274) which should automatically open the
  391. tool for debugging and development.
  392. ### Running tests
  393. ```bash
  394. moon run :lint :lock-check :install-check :test :check :build
  395. moon run root:combine-coverage
  396. ```
  397. CI uses `moon ci` with the same validation targets to run only tasks affected
  398. by the changed files and their dependencies. Pull requests compare the checked-out
  399. merge commit with the base commit; pushes compare with the previous commit.
  400. Python coverage is combined and uploaded only when Python tests produce coverage
  401. files.
  402. Changes to shared toolchain and CI configuration select all validation tasks.
  403. Project Moon configuration changes select that project's validation tasks.
  404. ### Running tasks with moon
  405. The standard Python server projects and the JavaScript MCP server are
  406. orchestrated with [moon](https://moonrepo.dev/). Tool versions are pinned in
  407. `.prototools`; after installing [proto](https://moonrepo.dev/docs/proto/install),
  408. install the pinned tools and run tasks from the repository root:
  409. ```bash
  410. proto install moon --immutable-lockfile
  411. moon setup
  412. moon run oci-compute-mcp-server:test
  413. moon run oci-javascript-mcp-server:test
  414. moon run root:lint
  415. moon run :build
  416. ```
  417. The shared CI setup action downloads a pinned proto release and verifies its
  418. archive against the SHA-256 stored beside the version in the action before
  419. extracting or running it. It then follows the same sequence shown above.
  420. Moon's version and platform checksums are recorded in `.protolock`; proto
  421. verifies the Moon download against the lockfile.
  422. After changing the Moon pin, run `proto install moon` on Linux x64 and macOS
  423. ARM64 and commit the generated `.protolock` with `.prototools`. For another
  424. platform, run `proto install moon` once to generate its record before using
  425. `--immutable-lockfile`.
  426. Moon uses each project's language-specific package definition: `pyproject.toml`
  427. and `uv.lock` for Python, and `package.json` and `package-lock.json` for
  428. JavaScript. Build, test, and publish tasks are defined in Moon.
  429. Other projects excluded from Moon continue to use the validation commands in
  430. their own README. Use `uv lock` or `uv sync` from a Python project's directory
  431. when updating or syncing that project's dependencies.
  432. Optional end-to-end tests can be run with `moon run root:e2e-tests` after
  433. following the setup in `tests/README.md`. Python container images with a
  434. `Containerfile` can be built with `moon run <project>:containerize`.
  435. ## Publishing
  436. Use the manually dispatched [Publish package](.github/workflows/publish.yml)
  437. workflow from `main`. Select `pypi` or `testpypi` with a Python Moon project ID
  438. or `all-python` to release every Moon-managed Python package. Select `npm` with
  439. `oci-javascript-mcp-server` for the JavaScript package. Moon runs checks and
  440. build before the workflow passes the distributions to its publish job. Releasing
  441. a Python server publishes `oracle-mcp-common` first and waits for it to appear
  442. on the selected index. Ordinary CI never invokes the publish tasks.
  443. Configure the `pypi`, `testpypi`, and `npm` GitHub environments with release
  444. approval rules and their respective `PYPI_TOKEN`, `TEST_PYPI_TOKEN`, and
  445. `NPM_TOKEN` secrets before running the workflow. The publish job reads only the
  446. secret for its selected registry. The Moon publish tasks require the release
  447. workflow's `RELEASE_PUBLISH` flag, and Python publishing also requires an
  448. explicit upload and check URL.
  449. To verify a Test PyPI package after publishing:
  450. ```bash
  451. uvx --refresh-package oracle.oci-api-mcp-server \
  452. --index https://test.pypi.org/simple \
  453. --from 'oracle.oci-api-mcp-server==<published-version>' \
  454. oracle.oci-api-mcp-server
  455. ```
  456. Replace `<published-version>` with the version you released.
  457. ## Contributing
  458. This project welcomes contributions from the community. Before submitting a pull
  459. request, please [review our contribution guide](./CONTRIBUTING.md).
  460. ## Security
  461. Please consult the [security guide](./SECURITY.md) for our responsible security
  462. vulnerability disclosure process.
  463. ## License
  464. <!-- The correct copyright notice format for both documentation and software
  465. is "Copyright (c) [year,] year Oracle and/or its affiliates."
  466. You must include the year the content was first released (on any platform) and
  467. the most recent year in which it was revised. -->
  468. Copyright (c) 2025 Oracle and/or its affiliates.
  469. Released under the Universal Permissive License v1.0 as shown at
  470. <https://oss.oracle.com/licenses/upl/>.
  471. ## Third-Party APIs
  472. 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.
  473. ## Disclaimer
  474. Users are responsible for their local environment and credential safety. Different language model selections may yield different results and performance.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.