cloudcostsmcp

Purpose

OpenCloudCosts is an open-source MCP (Model Context Protocol) server designed to provide AI assistants with real-time, structured cloud pricing data for AWS, GCP, and Azure. The core problem it solves is this: large language models' cloud pricing knowledge is frozen at their training cutoff, while cloud pricing continuously changes—instance types are constantly added and retired, the same instance type can vary in price by 20–40% across regions, spot markets fluctuate, and commitment discounts vary by account. Models cannot know your negotiated EDP rates, and they even struggle to reliably recall last year's list prices. OpenCloudCosts lets models call tools to get precise answers instead of guessing numbers out of thin air.

Main Capabilities

Coverage: Three Major Clouds, 16 Tools

Of these, 14 tools are fully available. Two entries are compatibility placeholders:search_pricing(a deprecated redirect from v0.8.x, retained for backward compatibility) and get_spot_history(registered in the Go server but not implemented, returning a structured "unavailable" response).

Credential Requirements by Provider

• AWS: No credentials are required for public pricing; effective pricing requires AWS credentials and setting OCC_AWS_ENABLE_COST_EXPLORER=true.
• GCP: Public pricing requires a free GCP API key (OCC_GCP_API_KEY); contract/effective pricing requires ADC credentials and billing.billingAccountPrice.get IAM permissions.
• Azure: Fully public, requiring no credentials, API key, or subscription. Azure Reserved VM pricing (1-year and 3-year terms) is available through the public Retail Prices API without credentials.

Performance and Reliability

• Concurrency:find_cheapest_region and find_available_regions use errgroup + semaphore, with up to 32 goroutines querying all available regions in parallel, with results sorted cheapest first;compare_bom simultaneously issues 8 concurrent provider calls across AWS, GCP, and Azure;compare_prices uses a semaphore with 10 concurrent region calls;get_prices_batch parallelizes across instance types within a region.
• Rate Limiting and Timeouts: The HTTP transport layer has a token bucket rate limit of 200 req/s (OCC_RATE_LIMIT); per-request deadline is 60s (OCC_REQUEST_TIMEOUT); each provider API call is 30s (OCC_PROVIDER_TIMEOUT); graceful SIGTERM drain is 15s (OCC_SHUTDOWN_TIMEOUT).
• Caching: Prices are stored in a concurrent in-memory cache (using sync.RWMutex read optimization), with atomic JSON persistence at ~/.cache/opencloudcosts/cache.json. TTL: public prices 24 hours (OCC_CACHE_TTL_HOURS), region/instance metadata 7 days (OCC_METADATA_TTL_DAYS), effective/contract rates 1 hour (OCC_EFFECTIVE_PRICE_TTL_HOURS). Caches survive binary updates. The Billing API's 401/403 responses are never cached, so credential rotation takes effect immediately.
• AWS Pricing: EC2/EBS/RDS public pricing uses targeted SKU API paths rather than downloading the full multi-GB bulk pricing files, keeping startup fast and avoiding large network loads.
• Error isolation: Raw exception text never enters the LLM context. All tool boundaries emit structured error envelopes; full tracebacks are logged only server-side. GCP contract pricing falls back to public list prices on authentication failure rather than exposing errors to the conversation.

Verification

OpenCloudCosts v1.0.0 achieves 234/234 (100%) on the LLM grounding test set, with zero XML hallucinations across the full suite. The test set covers 234 real pricing questions across the three major clouds: instance spot checks, cross-region comparisons, BOM estimates, multi-cloud comparisons, unit economics, AI model pricing, database pricing, storage pricing, discount summaries, egress pricing, availability queries, and network pricing. The primary verification model is qwen3.6-35b-128k running locally via llama-swap. Test set progress: 109/123 (Python v0.8.x) → 169/169 (v0.9.0) → 199/199 (v0.9.2) → 234/234 (v1.0.0). In addition, 643 Go unit tests across all providers and tools verify behavioral correctness and cross-provider API consistency.

Usage

Installation

• Option 1 — pip (simplest, cross-platform): The PyPI package wraps the native Go binary, requiring no Go toolchain.
• Option 2 — Homebrew (macOS / Linux).
• Option 3 — Binary download: Download the prebuilt binary from the latest release.
• Option 4 — Docker / containers: The image is about 15 MB (distroless scratch base, static binary). AWS and Azure public pricing require no credentials.
• Option 5 — Build from source.

Connecting to Claude Code

• Stdio (local process — recommended for single users): Add to ~/.claude/settings.json or the project's .mcp.json.
• HTTP (shared/remote server — one server, multiple clients): See deploy/kubernetes/ for the manifest. Build and push your own image, then reference it in deployment.yaml . Credentials are passed via environment variables or Kubernetes Secrets.

Testing

Test with MCP Inspector.

AWS Credentials

Minimal IAM policy for public pricing; additional permissions are required for effective pricing.

Configuration

All settings are via environment variables (prefix OCC_) or the .env file.

GCP Setup

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

• Option A — Free API key (recommended, 2-minute setup): Go to console.cloud.google.com/apis/credentials, create a project (free), and click Create Credentials → API Key. Or add OCC_GCP_API_KEY=AIza... to the .env file.
• Option B — Application Default Credentials (if already using gcloud).

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 actual discounted rates (EDP, custom pricing) via the Cloud Billing Pricing API v1beta. Requires: ADC credentials (gcloud auth application-default login), the billing.billingAccountPrice.get IAM permission on the billing account, and the billing account ID. Once configured, GCP-computed get_price responses will include effective_price block, showing the contract rate and discount percentage. When not configured, returns the public list price.

Azure Setup

Azure pricing is fully public—no credentials, API key, or subscription required. Azure instance type format: ARM SKU name, for example Standard_D4s_v3、Standard_E8s_v3、Standard_B2ms. Azure pricing terms:on_demand(default),reserved_ , etc.

Use Cases

1. Price the same workload across all three major clouds simultaneously: Use compare_bom to launch 8 concurrent provider calls at the same time, returning a breakdown by provider and by term as well as savings analysis.
2. Find the cheapest AWS region for a long-running compute workload: Use find_cheapest_region to fan out across all regions with 32 goroutines, returning the 5 cheapest.
3. Determine the effective AWS rate after a commitment: Use get_price with AWS credentials and OCC_AWS_ENABLE_COST_EXPLORER=true, returning the actual discounted rate and the public list price.
4. Break-even analysis for Azure serverless vs. always-on mode:estimate_unit_economics covers the Functions path,get_price covers VMs.
5. Unit economics for a SaaS product:estimate_bom prices the full stack,estimate_unit_economics calculates per-user and per-request costs.
6. AI token cost comparison: Vertex AI vs. Azure OpenAI: Use get_price with domain: ai to cover both providers.

Limitations

• Two tools are compatibility placeholders and do not provide real-time data:search_pricing(deprecated redirect) and get_spot_history(not implemented, returns a structured "unavailable" response).
• The GCP pricing API always requires at least one free API key and cannot access public pricing completely without credentials like AWS can.
• GCP contract/effective pricing requires ADC credentials and specific IAM permissions, making configuration relatively complex.
• Effective pricing (discounted rates) requires credentials and additional configuration for the corresponding cloud provider; when not configured, only public list prices are returned.
• Cache TTL means price data may lag by up to 24 hours (public prices), and the refresh_cache tool must be used to force a refresh.
• The project is an open-source MCP server, requires self-deployment and configuration, and does not provide a hosted service.