Metadata-Version: 2.1
Name: opencloudcosts
Version: 1.0.2
Summary: MCP server for cloud pricing (AWS, GCP, Azure)
Author: x7even
License: MIT
Requires-Python: >=3.8
Project-URL: Homepage, https://github.com/x7even/cloudcostsmcp
Project-URL: Source, https://github.com/x7even/cloudcostsmcp
Project-URL: Issues, https://github.com/x7even/cloudcostsmcp/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Other
Classifier: Topic :: Office/Business :: Financial
Description-Content-Type: text/markdown; charset=UTF-8

# OpenCloudCosts MCP

<!-- mcp-name: io.github.x7even/cloudcostsmcp -->

## Anchor AI FinOps to real, live cloud pricing.

An open source MCP server that gives AI assistants accurate cloud pricing data for AWS, GCP, and Azure.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/opencloudcosts)](https://pypi.org/project/opencloudcosts/)
[![Release](https://img.shields.io/github/v/release/x7even/cloudcostsmcp?include_prereleases)](https://github.com/x7even/cloudcostsmcp/releases/latest)

Supports both **public list pricing** (no credentials needed for AWS and Azure; GCP requires a free API key) and **effective (custom Private Pricing Agreement) rates** (post-discount: Reserved Instances, Savings Plans, CUDs, EDPs).

## Key Use Cases

- "What is the on-demand price of an m5.xlarge in us-east-1 vs ap-southeast-2, and what's the % delta?"
- "Give me a TCO estimate for this architecture: 3x m5.xlarge + 1x 500GB gp3 EBS in us-east-1"
- "What's the cost per user if I run this stack for 50,000 MAUs?"
- "List all c6g instances in eu-west-1 with >= 8 vCPUs"
- "What's my effective hourly rate on m5.xlarge after Savings Plans?"

## Tools (v1.0.0 — 16 tools)

**Pricing**

| Tool | Description |
|------|-------------|
| `get_price` | Unified pricing dispatcher — compute, storage, database, AI, networking, serverless, analytics, observability |
| `get_prices_batch` | Prices for multiple instance types in one call (concurrent) |
| `compare_prices` | Compare a spec across multiple regions with optional baseline deltas |
| `search_pricing` | Free-text search across the pricing catalog |

**Discovery**

| Tool | Description |
|------|-------------|
| `describe_catalog` | Full support matrix or targeted field guidance + copy-paste `example_invocation` for `get_price` |
| `list_regions` | All regions with friendly names |
| `list_instance_types` | Available instance types with vCPU/memory filters |

**Region Analysis**

| Tool | Description |
|------|-------------|
| `find_cheapest_region` | Cheapest region for any service spec, concurrently |
| `find_available_regions` | Every region where a service is available, sorted by price |
| `get_spot_history` | AWS spot price history and stability analysis (requires credentials) |

**FinOps**

| Tool | Description |
|------|-------------|
| `get_discount_summary` | Account-wide RI / Savings Plan / CUD utilisation (requires credentials) |
| `estimate_bom` | TCO for a multi-resource Bill of Materials |
| `estimate_unit_economics` | Cost per user/request/transaction |

**Cache**

| Tool | Description |
|------|-------------|
| `refresh_cache` | Invalidate pricing cache |
| `cache_stats` | Cache entry counts and DB size |

See [docs/tools.md](docs/tools.md) for full parameter reference and [docs/finops-guide.md](docs/finops-guide.md) for usage examples.

## Setup

### Option 1 — pip (easiest, cross-platform)

The PyPI package wraps the native Go binary — no Go toolchain needed.

```bash
pip install opencloudcosts
opencloudcosts            # stdio mode (for local MCP clients)
opencloudcosts --transport http --host 0.0.0.0 --port 8080  # HTTP mode
```

### Option 2 — binary download

Download the pre-built binary for your platform from the [latest release](https://github.com/x7even/cloudcostsmcp/releases/latest):

```bash
# Linux (amd64)
curl -L https://github.com/x7even/cloudcostsmcp/releases/latest/download/opencloudcosts_linux_amd64.tar.gz | tar xz
./opencloudcosts

# macOS (Apple Silicon)
curl -L https://github.com/x7even/cloudcostsmcp/releases/latest/download/opencloudcosts_darwin_arm64.tar.gz | tar xz
./opencloudcosts
```

### Option 3 — Docker / container

```bash
# Build the image first (no pre-built image is published)
cd opencloudcosts-go
docker build -t opencloudcosts:local .

# Run — HTTP transport, bound to all interfaces
docker run -p 8080:8080 \
  -e OCC_GCP_API_KEY=AIza... \
  -v ~/.aws:/root/.aws:ro \
  opencloudcosts:local
```

The image is ~15 MB (distroless scratch base, static binary). No credentials are
required for AWS and Azure public pricing.

### Option 4 — build from source

```bash
git clone https://github.com/x7even/cloudcostsmcp
cd cloudcostsmcp/opencloudcosts-go
CGO_ENABLED=0 go build -o opencloudcosts ./cmd/opencloudcosts
./opencloudcosts
```

### Connect to Claude Code

**Stdio (local process — recommended for single-user)**

Add to `~/.claude/settings.json` or your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "cloudcost": {
      "command": "opencloudcosts",
      "env": {
        "OCC_GCP_API_KEY": "AIza..."
      }
    }
  }
}
```

**HTTP (shared/remote server — one server, many clients)**

```json
{
  "mcpServers": {
    "cloudcost": {
      "transport": "http",
      "url": "http://localhost:8080/"
    }
  }
}
```

### Kubernetes

See `deploy/kubernetes/` for manifests. Build and push your own image (see Docker section above), then reference it in `deployment.yaml`.
Credentials are passed via environment variables or Kubernetes Secrets — same variable
names as the Docker examples above.

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector opencloudcosts
```

## AWS Credentials

| Feature | Credentials needed |
|---------|--------------------|
| Public pricing (EC2, EBS, RDS list prices) | None |
| Effective pricing (RI / SP discounts) | AWS credentials + `OCC_AWS_ENABLE_COST_EXPLORER=true` |

Minimal IAM policy for public pricing:
```json
{
  "Effect": "Allow",
  "Action": ["pricing:GetProducts", "pricing:DescribeServices", "pricing:GetAttributeValues"],
  "Resource": "*"
}
```

Add these for effective pricing:
```json
"ce:GetCostAndUsage", "savingsplans:DescribeSavingsPlans", "savingsplans:DescribeSavingsPlanRates"
```

## Configuration

All settings via environment variables (prefix `OCC_`) or `.env` file:

| Variable | Default | Description |
|----------|---------|-------------|
| `OCC_CACHE_TTL_HOURS` | 24 | Public price cache TTL |
| `OCC_AWS_ENABLE_COST_EXPLORER` | false | Enable AWS effective pricing (costs $0.01/call) |
| `OCC_DEFAULT_REGIONS` | us-east-1,us-west-2 | Default regions |
| `AWS_PROFILE` | (default chain) | AWS credentials profile |
| `OCC_GCP_BILLING_ACCOUNT_ID` | (none) | GCP billing account ID for contract/effective pricing |

## Caching

Prices are cached in SQLite at `~/.cache/opencloudcosts/pricing.db`. Public list prices are cached for 24 hours — AWS pricing changes infrequently. Use the `refresh_cache` tool to force a refresh.

## GCP Setup

Unlike AWS (which has public bulk pricing endpoints), GCP's pricing API always requires at least a free API key. No credit card or billing account is needed.

**Option A — Free API key (recommended, 2 min setup):**
1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
2. Create a Project if you don't have one (free)
3. Click **Create Credentials → API key**
4. Set the key:

```bash
export OCC_GCP_API_KEY=AIza...
```

Or add `OCC_GCP_API_KEY=AIza...` to your `.env` file.

**Option B — Application Default Credentials** (if you already use `gcloud`):
```bash
gcloud auth application-default login
# or set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

**GCP instance type format:** `{family}-{series}-{vcpus}` e.g. `n2-standard-4`, `e2-highmem-8`, `c2-standard-16`

### GCP Contract / Effective Pricing

If you have a negotiated pricing contract with Google Cloud, you can retrieve your actual discounted rates (EDP, custom pricing) via the Cloud Billing Pricing API v1beta. This requires:

1. ADC credentials: `gcloud auth application-default login`
2. `billing.billingAccountPrice.get` IAM permission on your billing account
3. Your billing account ID:

```bash
export OCC_GCP_BILLING_ACCOUNT_ID=012345-567890-ABCDEF
```

With this configured, `get_price` responses for GCP compute will include an `effective_price` block showing your contract rate and discount percentage. Without it, public list prices are returned unchanged.

## Azure Setup

Azure pricing is fully public — no credentials, API key, or subscription needed.

```bash
# No configuration needed — works out of the box
uv run opencloudcosts
```

**Azure instance type format:** ARM SKU names e.g. `Standard_D4s_v3`, `Standard_E8s_v3`, `Standard_B2ms`

**Azure pricing terms:** `on_demand` (default), `reserved_1yr`, `reserved_3yr`, `spot`

**Azure regions:** ARM region names e.g. `eastus`, `westeurope`, `southeastasia` (use `list_regions` for full list)

**Azure supported services:**

| Domain | Service | Description |
|--------|---------|-------------|
| compute | vm | Virtual Machines — all families, Linux/Windows, on-demand/spot/reserved |
| storage | managed_disks | Premium SSD, Standard SSD, Standard HDD, Ultra Disk |
| storage | blob | Blob Storage |
| database | sql | Azure SQL Database, Azure DB for MySQL/PostgreSQL — vCore tiers, HA, reserved |
| database | cosmos | Cosmos DB — provisioned (per 100 RU/s), serverless, autoscale |
| container | aks | AKS cluster management fee (free tier or $0.10/hr Standard) |
| serverless | azure_functions | Functions Consumption plan — per GB-second + per execution |
| ai | openai | Azure OpenAI — GPT-4o, GPT-4, GPT-3.5-Turbo, o1, embeddings |
| inter_region_egress | — | Outbound data transfer — internet and inter-region, Zone 1 rates, 5 GB/month free |

**GCP pricing terms:** `on_demand` (default), `spot` (preemptible), `cud_1yr`, `cud_3yr`

## Security

OpenCloudCosts can access sensitive billing data when configured with cloud credentials (AWS Cost Explorer, GCP billing, Azure contract pricing). Follow these guidelines to keep that data safe.

**Credential hygiene**
- Use dedicated, least-privilege credentials — read-only access scoped to pricing and billing APIs only. Never use root, owner, or admin credentials.
- AWS: create an IAM user/role with only `ce:GetCostAndUsage`, `pricing:GetProducts`, and `savingsplans:Describe*` permissions.
- Store credentials in `.env` (see `.env.example`) and never commit that file to version control.

**Transport security**
- The default `stdio` transport is safe — the server runs as a local process with no network exposure.
- If you use `--transport http`, never expose it publicly without a reverse proxy and authentication in front of it. Treat it as an internal service.

**MCP client trust**
- Only add this server to MCP client configs you control.
- Avoid running it alongside untrusted third-party MCP servers — a malicious server can craft prompts that cause the LLM to call your billing tools and relay the results.

**What this server can access**
With credentials configured: actual spend, contract/negotiated pricing, reservation and savings plan data. Understand this before granting access in shared or multi-user environments.

## Recent releases

- **v0.9.1** ✅ GCP egress contract pricing; fix `PricingResult.source` Literal
- **v0.9.2** ✅ Azure OpenAI model matching fix; Azure Functions pricing fix; `list_instance_types` cap; AWS bulk pricing via ijson; 199-prompt harness suite
- **v1.0.0** ✅ Go rewrite — static binary, dual stdio/HTTP transport, 16 tools, `compare_bom` cross-cloud workload comparison, concurrent region fan-out (32 goroutines), Azure o1-mini SKU fix; **234/234 (100%) LLM grounding harness**
- **v1.0.1** ✅ PyPI package description; CI Trusted Publisher fix; `go install` tag
