Metadata-Version: 2.4
Name: ct-kubecost-mcp-server
Version: 0.2.0
Summary: CloudThinker stdio MCP server for KubeCost / OpenCost: reads KUBECOST_* env at startup, auto-connects to the cost API, and serves read-only Kubernetes cost allocation, assets, cloud cost, and efficiency (right-sizing) tools.
Project-URL: Homepage, https://github.com/cloudthinker/ct-kubecost-mcp-server
Author: CloudThinker
License: Apache-2.0
License-File: LICENSE
Keywords: cloudthinker,cost,finops,kubecost,kubernetes,llm,mcp,opencost
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.0
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# ct-kubecost-mcp-server

A CloudThinker stdio MCP server for [KubeCost](https://www.kubecost.com/) and
[OpenCost](https://www.opencost.io/). It **auto-connects from environment
variables** and serves read-only Kubernetes cost tools, so it drops into
CloudThinker's env-injection connection model.

There is no pip-installable upstream MCP to wrap — OpenCost's MCP server is Go,
compiled into its cost-model binary (`pkg/mcp/server.go`). This server authors the
tools directly against the KubeCost/OpenCost HTTP cost API, mirroring OpenCost's
four query types: **allocation, asset, cloudcost, efficiency**.

## What it does

- Reads `KUBECOST_*` env vars at startup and connects to the cost API.
- Serves read-only tools over **stdio**.
- KubeCost serves the API under `/model` (`/model/allocation`); bare OpenCost serves
  it at the root (`/allocation`). Controlled by `KUBECOST_API_PREFIX` (default `/model`).

## Run

```bash
uvx --from ct-kubecost-mcp-server@0.2.0 ct-kubecost-mcp-server
```

## Environment

| Var | Required | Default | Purpose |
|---|---|---|---|
| `KUBECOST_URL` | yes | — | base URL of the KubeCost/OpenCost endpoint |
| `KUBECOST_AUTH_TYPE` | no | `none` | `none` \| `bearer` \| `basic` |
| `KUBECOST_TOKEN` | when `bearer` | — | bearer token (`Authorization: Bearer …`) |
| `KUBECOST_USERNAME` | when `basic` | — | HTTP basic username |
| `KUBECOST_PASSWORD` | when `basic` | — | HTTP basic password |
| `KUBECOST_API_PREFIX` | no | `/model` | path prefix; set empty (`""`) for bare OpenCost |
| `KUBECOST_INSECURE_SKIP_VERIFY` | no | `false` | `true` → skip TLS verification |
| `LOG_LEVEL` | no | `info` | mapped to `FASTMCP_LOG_LEVEL` |

## Tools (read-only)

| Tool | Purpose | API |
|---|---|---|
| `get_allocation` | in-cluster cost by namespace/controller/pod (chargeback) | `GET {prefix}/allocation` |
| `get_assets` | cloud asset cost (nodes, disks, network) | `GET {prefix}/assets` |
| `get_cloud_cost` | out-of-cluster cloud bill | `GET {prefix}/cloudCost` |
| `get_efficiency` | right-sizing — requested vs used, estimated wasted cost | derived from `/allocation` |
| `health` | reachability + auth probe | `GET {prefix}/allocation?window=1h` |

Time windows accept KubeCost/OpenCost formats: `today`, `week`, `month`, `Nd`
(e.g. `7d`), `Nh`, or an RFC3339 / unix-timestamp range.

## Build

```bash
python -m build        # or: hatch build
```

## License

Apache-2.0.
