Metadata-Version: 2.4
Name: cloudrift-mcp
Version: 0.1.0
Summary: Read-only MCP server exposing CloudRift cloud-waste findings and verified-savings receipts to AI assistants
Author-email: CloudRift <support@cloudrift.tech>
License: MIT
Project-URL: Homepage, https://cloudrift.tech
Keywords: mcp,cloudrift,finops,cloud-cost,waste,savings
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2
Requires-Dist: httpx>=0.27
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# cloudrift-mcp

An [MCP](https://modelcontextprotocol.io) server that gives your AI
assistant (Claude Code, Claude Desktop, Cursor, and any other MCP
client) read-only access to your own
[CloudRift](https://cloudrift.tech) data: cloud-waste findings,
optimization recommendations, cost summaries, budgets, and the
verified-savings ledger. The thesis is simple: in the agent era, your
cost data should be queryable by the assistants you already work in -
"what are my ten most expensive orphaned resources?" or "how much has
CloudRift actually saved us, and how is that number computed?" should
be one question away, answered from your tenant's live findings and
receipts rather than a stale export.

Read-only by construction. Every tool is a GET against the CloudRift
public API, scoped to the tenant that owns the API key. No tool
mutates anything, and no tool accepts a credential argument - the key
comes from the environment only.

## Quickstart

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/), or pip:

```
uvx cloudrift-mcp        # no install step
pip install cloudrift-mcp && cloudrift-mcp
```

Create an API key in CloudRift (Settings > API Keys) with read-only
scopes, then export it as `CLOUDRIFT_API_KEY`.

### Claude Code

```
claude mcp add cloudrift --env CLOUDRIFT_API_KEY=crk_live_... -- uvx cloudrift-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings > Developer > Edit
Config):

```json
{
  "mcpServers": {
    "cloudrift": {
      "command": "uvx",
      "args": ["cloudrift-mcp"],
      "env": {
        "CLOUDRIFT_API_KEY": "crk_live_..."
      }
    }
  }
}
```

## Environment variables

| Variable            | Required | Meaning                                            |
| ------------------- | -------- | -------------------------------------------------- |
| `CLOUDRIFT_API_KEY` | yes      | A CloudRift API key. Without it the server starts, but every tool returns a clear CONFIG error. |
| `CLOUDRIFT_API_URL` | no       | API origin; defaults to `https://cloudrift.tech`.  |

## Tools

All tools are read-only GETs with a 30 second timeout. Lists are
capped, and every capped result states the cap and the full totals, so
a partial view is never silent.

| Tool                  | Arguments                   | Endpoint                  | Returns |
| --------------------- | --------------------------- | ------------------------- | ------- |
| `list_waste_findings` | `account_id?`, `limit?` (default 25, max 100) | `/api/v1/resources` | Waste findings: orphaned resources first, then optimization candidates, monthly cost descending, with full waste totals. |
| `get_recommendations` | `account_id?` (filtered locally) | `/api/v1/recommendations` | Optimization recommendations, estimated monthly savings descending (top 50), with the summed savings across all matches. |
| `get_cost_summary`    | -                           | `/api/v1/costs/summary`   | Monthly spend, orphaned (waste) cost, annual savings potential, per-account breakdown, latest scan date. |
| `get_savings_receipts`| -                           | `/api/v1/receipts`        | The verified-savings ledger: entries labelled estimated / confirmed / billing_verified, per-status totals, and the API's `basis` string verbatim (how returned_to_date is computed). Requires CloudRift >= 2026-09-30. |
| `get_budgets`         | -                           | `/api/v1/budgets`         | Configured spend budgets with warning / critical thresholds. |

Errors come back as one honest line - `API_ERROR: CloudRift API
returned 403 for GET /api/v1/costs/summary: This API key is missing
the required scope: read:costs.` - never a stack trace.

## Security

- **Use a read-only key.** Grant only the `read:*` scopes
  (`read:resources`, `read:recommendations`, `read:costs`,
  `read:budgets`) when you mint the key. This server only ever issues
  GETs, so a broader key buys nothing and risks more.
- **Env-only auth.** The key is read from `CLOUDRIFT_API_KEY` and sent
  as `Authorization: Bearer`. No tool accepts a key as an argument (a
  test enforces that no credential-shaped field exists in any tool
  schema), and the key is never echoed into tool results or error
  messages.
- **Tenant-scoped by the API.** The CloudRift public API scopes every
  query to the key owner's account; this server adds no cross-tenant
  reach.
- **Bounded requests.** At most five pages of 200 items are fetched
  per tool call, and CloudRift rate-limits each key to 120
  requests/minute.

## License

MIT. See [LICENSE](LICENSE).
