# OKE MCP Server
Model Context Protocol (MCP) server for **Oracle Container Engine for Kubernetes (OKE)**. It lets MCP‑aware chat clients (e.g. Claude Desktop, VS Code Agent, custom CLI) **inspect, query and troubleshoot** your OKE clusters through a small set of safe, composable tools.
---
## ✨ Highlights
- **Lean, LLM‑friendly APIs** – small, consistent payloads (`{items,next,error}` / `{item,error}`) with optional `verbose` and `hints`.
- **OCI auth that “just works”** – supports **security token** (local dev) and **API keys**.
- **No venv required** – run with **uvx**: `uvx oke-mcp-server --transport stdio`.
- **Token rotation** – refresh without restart using the `auth_refresh` tool.
- **Production‑ready ergonomics** – clear errors, pagination, predictable shapes.
---
## Requirements
- **Python** 3.10+ (3.11+ recommended)
- **uv** (recommended): <https://github.com/astral-sh/uv>
- **OCI credentials** configured locally (see below)
Optional:
- MCP host/client (Claude Desktop, VS Code Agent Mode, etc.)
---
## Install & Run (recommended)
Run the published package with uvx:
```bash
uvx oke-mcp-server --transport stdio
```
Or run a specific version:
```bash
uvx --from oke-mcp-server==0.2.* oke-mcp-server --transport stdio
```
> The server speaks MCP over **stdio**. Most MCP hosts handle initialization automatically. For raw testing you can still send JSON‑RPC (see “Quick JSON‑RPC test”).
---
## Configure Authentication
### Option A — Security Token (best for local dev)
1. Sign in via the OCI Console/CLI to obtain a **security token**.
2. In your `~/.oci/config` profile (e.g. `DEFAULT`) include:
```ini
[DEFAULT]
tenancy=ocid1.tenancy.oc1..aaaa...
region=eu-frankfurt-1
user=ocid1.user.oc1..aaaa... # usually present; not used by STS signer
key_file=/path/to/your/api_key.pem # keep if you also use API key flows
fingerprint=XX:XX:... # same as above
security_token_file=/path/to/token # REQUIRED for STS
```
3. Export (or set in your MCP host env):
```bash
export OCI_CLI_AUTH=security_token
```
4. (When the token expires) call the MCP tool:
```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"auth_refresh","arguments":{}}}
```
### Option B — API Key
Use your standard `~/.oci/config` profile with `user`, `key_file`, `fingerprint`, `tenancy`, `region`. Do **not** set `OCI_CLI_AUTH=security_token`.
> The server also honors `OKE_COMPARTMENT_ID` and `OKE_CLUSTER_ID` environment variables as defaults.
---
## Using with an MCP Host
### Claude Desktop (example)
Settings → MCP Servers → Add:
```json
{
"name": "oke",
"command": "uvx",
"args": ["oke-mcp-server", "--transport", "stdio"],
"env": {
"OCI_CLI_AUTH": "security_token",
"OKE_COMPARTMENT_ID": "ocid1.compartment.oc1..aaaa...",
"OKE_CLUSTER_ID": "ocid1.cluster.oc1.eu-frankfurt-1.aaaa..."
}
}
```
That’s it—Claude will list the tools and can call them during chat.
---
## Quick JSON‑RPC test (manual)
Start the server:
```bash
uvx oke-mcp-server --transport stdio
```
Then send:
```json
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"0.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"meta_health","arguments":{}}}
```
---
## Tools (stable set)
All list tools return:
```json
{ "items": [...], "next": "<token|null>", "error": null, "meta": { ... } }
```
Single‑item tools return:
```json
{ "item": { ... }, "error": null, "meta": { ... } }
```
Common inputs:
- `limit` (default 20), `continue_token` (pagination)
- `verbose: bool` (include extra details)
- `hints: bool` (include lightweight graph hints where applicable)
- `auth: "security_token" | null` (override; otherwise server uses env/defaults)
### Meta / Config
- **meta_health** → `{server, version, defaults, effective}`
- **meta_env** → redacted env snapshot for diagnostics
- **auth_refresh** → re‑loads auth (use after rotating security token)
- **config_get_effective_defaults / config_set_defaults** → manage fallback OCIDs
### OKE / Kubernetes
- **k8s_list** — list Pods, Services, Namespaces, Nodes, Deployments, ReplicaSets, Endpoints, EndpointSlices, Ingress, Gateway, HTTPRoute, PVC, PV, StorageClass
- **k8s_get** — get a single resource by kind/namespace/name
- **oke_get_pod_logs** — stream recent logs from a container (supports `tail_lines`, `since_seconds`, `previous`, `timestamps`)
- **oke_list_clusters / oke_get_cluster** — cluster discovery and details (OCI)
> For public logs on OKE, ensure worker nodes allow the API->kubelet path: **TCP/10250** from the control‑plane CIDR/NSG. Timeouts when calling `read_namespaced_pod_log` typically mean this network path is blocked.
---
## Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| `{'user':'missing'}` from OCI SDK | No valid signer or profile | Set `OCI_CLI_AUTH=security_token` **or** ensure `~/.oci/config` has `user/key_file/fingerprint` |
| TLS bundle not found | Wrong Python cert path | Ensure `certifi` is installed in the environment running the server |
| Logs 500 / i/o timeout to `:10250` | Control‑plane → node kubelet blocked | Open **TCP/10250** from API endpoint CIDR in Security List / NSG |
| Tool says `cluster_id required` | No defaults present | Set `OKE_CLUSTER_ID` env or call `config_set_defaults` |
---
## Project Structure
```
oke_mcp_server/
__init__.py
main.py
auth.py
config_store.py
tools/
k8s.py
oke_cluster.py
pyproject.toml
Makefile
```
Raw data
{
"_id": null,
"home_page": null,
"name": "oke-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "MCP, Oracle, OKE, Kubernetes, LLM, DevTools",
"author": "Ron Sevet",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/27/28/fcbb2b7bdf04b6428082960bb6f3c7c6b0cd08c622d19ed6fa47ad5e3bf2/oke_mcp_server-0.1.5.tar.gz",
"platform": null,
"description": "# OKE MCP Server\n\nModel Context Protocol (MCP) server for **Oracle Container Engine for Kubernetes (OKE)**. It lets MCP\u2011aware chat clients (e.g. Claude Desktop, VS Code Agent, custom CLI) **inspect, query and troubleshoot** your OKE clusters through a small set of safe, composable tools.\n\n---\n\n## \u2728 Highlights\n\n- **Lean, LLM\u2011friendly APIs** \u2013 small, consistent payloads (`{items,next,error}` / `{item,error}`) with optional `verbose` and `hints`.\n- **OCI auth that \u201cjust works\u201d** \u2013 supports **security token** (local dev) and **API keys**.\n- **No venv required** \u2013 run with **uvx**: `uvx oke-mcp-server --transport stdio`.\n- **Token rotation** \u2013 refresh without restart using the `auth_refresh` tool.\n- **Production\u2011ready ergonomics** \u2013 clear errors, pagination, predictable shapes.\n\n---\n\n## Requirements\n\n- **Python** 3.10+ (3.11+ recommended)\n- **uv** (recommended): <https://github.com/astral-sh/uv>\n- **OCI credentials** configured locally (see below)\n\nOptional:\n- MCP host/client (Claude Desktop, VS Code Agent Mode, etc.)\n\n---\n\n## Install & Run (recommended)\n\nRun the published package with uvx:\n\n```bash\nuvx oke-mcp-server --transport stdio\n```\n\nOr run a specific version:\n\n```bash\nuvx --from oke-mcp-server==0.2.* oke-mcp-server --transport stdio\n```\n\n> The server speaks MCP over **stdio**. Most MCP hosts handle initialization automatically. For raw testing you can still send JSON\u2011RPC (see \u201cQuick JSON\u2011RPC test\u201d).\n\n---\n\n## Configure Authentication\n\n### Option A \u2014 Security Token (best for local dev)\n\n1. Sign in via the OCI Console/CLI to obtain a **security token**.\n2. In your `~/.oci/config` profile (e.g. `DEFAULT`) include:\n ```ini\n [DEFAULT]\n tenancy=ocid1.tenancy.oc1..aaaa...\n region=eu-frankfurt-1\n user=ocid1.user.oc1..aaaa... # usually present; not used by STS signer\n key_file=/path/to/your/api_key.pem # keep if you also use API key flows\n fingerprint=XX:XX:... # same as above\n security_token_file=/path/to/token # REQUIRED for STS\n ```\n3. Export (or set in your MCP host env):\n ```bash\n export OCI_CLI_AUTH=security_token\n ```\n4. (When the token expires) call the MCP tool:\n ```json\n {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"auth_refresh\",\"arguments\":{}}}\n ```\n\n### Option B \u2014 API Key\n\nUse your standard `~/.oci/config` profile with `user`, `key_file`, `fingerprint`, `tenancy`, `region`. Do **not** set `OCI_CLI_AUTH=security_token`.\n\n> The server also honors `OKE_COMPARTMENT_ID` and `OKE_CLUSTER_ID` environment variables as defaults.\n\n---\n\n## Using with an MCP Host\n\n### Claude Desktop (example)\n\nSettings \u2192 MCP Servers \u2192 Add:\n\n```json\n{\n \"name\": \"oke\",\n \"command\": \"uvx\",\n \"args\": [\"oke-mcp-server\", \"--transport\", \"stdio\"],\n \"env\": {\n \"OCI_CLI_AUTH\": \"security_token\",\n \"OKE_COMPARTMENT_ID\": \"ocid1.compartment.oc1..aaaa...\",\n \"OKE_CLUSTER_ID\": \"ocid1.cluster.oc1.eu-frankfurt-1.aaaa...\"\n }\n}\n```\n\nThat\u2019s it\u2014Claude will list the tools and can call them during chat.\n\n---\n\n## Quick JSON\u2011RPC test (manual)\n\nStart the server:\n\n```bash\nuvx oke-mcp-server --transport stdio\n```\n\nThen send:\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"manual\",\"version\":\"0.0.0\"}}}\n{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\",\"params\":{}}\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"meta_health\",\"arguments\":{}}}\n```\n\n---\n\n## Tools (stable set)\n\nAll list tools return:\n\n```json\n{ \"items\": [...], \"next\": \"<token|null>\", \"error\": null, \"meta\": { ... } }\n```\n\nSingle\u2011item tools return:\n\n```json\n{ \"item\": { ... }, \"error\": null, \"meta\": { ... } }\n```\n\nCommon inputs:\n- `limit` (default 20), `continue_token` (pagination)\n- `verbose: bool` (include extra details) \n- `hints: bool` (include lightweight graph hints where applicable)\n- `auth: \"security_token\" | null` (override; otherwise server uses env/defaults)\n\n### Meta / Config\n- **meta_health** \u2192 `{server, version, defaults, effective}`\n- **meta_env** \u2192 redacted env snapshot for diagnostics\n- **auth_refresh** \u2192 re\u2011loads auth (use after rotating security token)\n- **config_get_effective_defaults / config_set_defaults** \u2192 manage fallback OCIDs\n\n### OKE / Kubernetes\n- **k8s_list** \u2014 list Pods, Services, Namespaces, Nodes, Deployments, ReplicaSets, Endpoints, EndpointSlices, Ingress, Gateway, HTTPRoute, PVC, PV, StorageClass\n- **k8s_get** \u2014 get a single resource by kind/namespace/name\n- **oke_get_pod_logs** \u2014 stream recent logs from a container (supports `tail_lines`, `since_seconds`, `previous`, `timestamps`)\n- **oke_list_clusters / oke_get_cluster** \u2014 cluster discovery and details (OCI)\n\n> For public logs on OKE, ensure worker nodes allow the API->kubelet path: **TCP/10250** from the control\u2011plane CIDR/NSG. Timeouts when calling `read_namespaced_pod_log` typically mean this network path is blocked.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely Cause | Fix |\n|---|---|---|\n| `{'user':'missing'}` from OCI SDK | No valid signer or profile | Set `OCI_CLI_AUTH=security_token` **or** ensure `~/.oci/config` has `user/key_file/fingerprint` |\n| TLS bundle not found | Wrong Python cert path | Ensure `certifi` is installed in the environment running the server |\n| Logs 500 / i/o timeout to `:10250` | Control\u2011plane \u2192 node kubelet blocked | Open **TCP/10250** from API endpoint CIDR in Security List / NSG |\n| Tool says `cluster_id required` | No defaults present | Set `OKE_CLUSTER_ID` env or call `config_set_defaults` |\n\n---\n\n## Project Structure\n\n```\noke_mcp_server/\n __init__.py\n main.py\n auth.py\n config_store.py\n tools/\n k8s.py\n oke_cluster.py\npyproject.toml\nMakefile\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Minimal MCP server for managing Oracle OKE & Kubernetes, optimized for LLMs.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/ronsevetoci/oke-mcp-server",
"Issues": "https://github.com/ronsevetoci/oke-mcp-server/issues",
"Source": "https://github.com/ronsevetoci/oke-mcp-server"
},
"split_keywords": [
"mcp",
" oracle",
" oke",
" kubernetes",
" llm",
" devtools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9354da1f70f49ba0b43b152417d21f4c70136e28eb461fd7500fecee82bccf26",
"md5": "12adcc8352bb512a8e2d11eedc16c3f3",
"sha256": "883710478c20b14ecf5ab7805e039cfb360e183e22b94f5659d8c2c37c61f4fd"
},
"downloads": -1,
"filename": "oke_mcp_server-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12adcc8352bb512a8e2d11eedc16c3f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 37220,
"upload_time": "2025-08-14T06:14:55",
"upload_time_iso_8601": "2025-08-14T06:14:55.555008Z",
"url": "https://files.pythonhosted.org/packages/93/54/da1f70f49ba0b43b152417d21f4c70136e28eb461fd7500fecee82bccf26/oke_mcp_server-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2728fcbb2b7bdf04b6428082960bb6f3c7c6b0cd08c622d19ed6fa47ad5e3bf2",
"md5": "7bbd96d8b5828dbde1b5ff89378b4c57",
"sha256": "82aebc147cff42471b64a0e0cfdf6edd9746924745fa3f0f2859514b1b38a82b"
},
"downloads": -1,
"filename": "oke_mcp_server-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "7bbd96d8b5828dbde1b5ff89378b4c57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 35244,
"upload_time": "2025-08-14T06:14:57",
"upload_time_iso_8601": "2025-08-14T06:14:57.009058Z",
"url": "https://files.pythonhosted.org/packages/27/28/fcbb2b7bdf04b6428082960bb6f3c7c6b0cd08c622d19ed6fa47ad5e3bf2/oke_mcp_server-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 06:14:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ronsevetoci",
"github_project": "oke-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "oke-mcp-server"
}
JSON
