Skip to main content
Glama
gcp-calculator-mcp

gcp-calculator-mcp

by carlosrgomes
README.md
# Google Cloud Pricing Calculator MCP Server (`gcp-calculator-mcp`)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-1a73e8)](https://modelcontextprotocol.io/)

Open-source **Model Context Protocol (MCP)** server for the official [Google Cloud Pricing Calculator](https://cloud.google.com/products/calculator).

Give AI assistants (Claude Code, Claude Desktop, Antigravity, Cursor, and any MCP-compatible client) direct access to all **64 Google Cloud products**, real-time conditional schemas, intelligent machine-type recommendations, and the ability to **create, inspect, and edit official shareable Google Cloud Pricing Calculator links**.

Runs locally over **`stdio`** or remotely as a **stateless Streamable HTTP** server (open, zero database, zero auth required) — ready for Docker and Google Cloud Run.

---

## Live Result Preview

Ask your AI assistant in plain English to estimate a multi-service GCP architecture, and it generates a **real, editable Google Cloud Pricing Calculator link** with itemized SKU pricing:

### Interactive Official Calculator (`calculatorUrl`)
![Google Cloud Pricing Calculator generated by gcp-calculator-mcp](assets/calculator-official.png)

### Cost Estimate Summary (`previewUrl`)
![Google Cloud Cost Estimate Summary generated by gcp-calculator-mcp](assets/calculator-preview.png)

---

## Features & Available Tools (6 Tools)

| Tool | Description |
| :--- | :--- |
| `list_products` | Lists and searches all **64 products** and their subservices directly from the official Google Cloud Pricing Calculator catalog. |
| `get_product_schema` | Returns the complete configuration schema for any product: subservices, field IDs, labels, UI section headers, `qualifiedLabel`, valid dropdown options, numeric min/max bounds, and dynamically evaluated conditional rules. |
| `recommend_machine_type` | Recommends the best predefined machine types (e.g., `e2-standard-4`, `n4-highmem-8`, `c3-standard-4`) or custom machine sizing given target `vcpus` and `memoryGb`, automatically detecting **Extended Memory** requirements. |
| `create_estimate` | Creates a multi-service estimate in the official Google Cloud Pricing Calculator and returns the editable shareable URL (`?dl=...`), preview URL (`/estimate-preview/...`), total monthly cost, and itemized SKU breakdown. |
| `get_estimate` | Opens any existing `?dl=...` or `/estimate-preview/...` calculator link and returns all configured services, field values, SKU line items, and monthly costs. |
| `update_estimate` | Modifies an existing calculator link (changes instance counts, machine types, memory, disks, regions, CUDs, or adds/removes services) and returns the new updated link with a cost comparison. |

---

## Example Prompts

Once connected to your MCP client, you can use natural language prompts like these:

### 1. Multi-Service Architecture Estimate
> *"Create a Google Cloud Pricing Calculator estimate in `us-central1` (USD) for:*
> *- 3x `e2-standard-4` Compute Engine VMs with 100 GiB Balanced Persistent Disk each (Web & API Servers)*
> *- 1x Cloud SQL for PostgreSQL instance with High Availability and 200 GiB SSD storage*
> *- 2 TB of Standard Cloud Storage for static assets and backups*
> *Give me the monthly breakdown and the official calculator link."*

**Actual Tool Output:**
```json
{
  "estimateId": "CiQ0MjcxMTM3Yy1jMjczLTRjYzktYWY2MS1kZWY2MjYzZTczM2MQAQ==",
  "calculatorUrl": "https://cloud.google.com/products/calculator?hl=en&dl=...",
  "previewUrl": "https://cloud.google.com/products/calculator/estimate-preview/CiQ0MjcxMTM3Yy1jMjczLTRjYzktYWY2MS1kZWY2MjYzZTczM2MQAQ%3D%3D?hl=en",
  "currency": "USD",
  "totalMonthlyCost": 629.62,
  "serviceCount": 3,
  "services": [
    {
      "customLabel": "Web & API Servers (3x e2-standard-4)",
      "productName": "Compute Engine",
      "monthlyCost": 323.51
    },
    {
      "customLabel": "Primary PostgreSQL DB (HA)",
      "productName": "Cloud SQL",
      "monthlyCost": 265.25
    },
    {
      "customLabel": "Static Assets & Backups (2 TB)",
      "productName": "Cloud Storage",
      "monthlyCost": 40.86
    }
  ]
}
```

### 2. Machine Type Recommendation
> *"What is the best GCP machine type for a workload needing 8 vCPUs and 96 GiB of RAM in the N2 series? Check whether Extended Memory is required."*

### 3. Edit an Existing Calculator Link
> *"Take this Google Cloud calculator link `<paste ?dl=... URL>`, scale the web servers from 3 to 6 instances, apply a 3-year Committed Use Discount, and add a Cloud Load Balancing service. Show me the before/after monthly cost difference."*

### 4. Inspect & Audit a Shared Estimate
> *"Inspect this GCP calculator link `<paste URL>` and list every service, region, machine type, and SKU cost in a Markdown table."*

### 5. Compare Regions or Pricing Models
> *"Compare the monthly cost of running 4x `c3-standard-8` instances in `us-central1` vs. `southamerica-east1` with On-Demand vs. 1-year CUD vs. Spot VMs."*

---

## Installation & Setup Guide

### Prerequisites

- **Node.js** `>= 20.0.0` (or **Docker** for containerized execution)
- **npm** (included with Node.js)

### 1. Clone, Install, and Build

```bash
git clone https://github.com/carlosrgomes/calculator-gcp-mcp.git
cd calculator-gcp-mcp
npm ci
npm run build
```

---

### 2. Option A — Local Mode (`--stdio`) *(Recommended for Desktop / CLI Clients)*

No ports or environment variables required. Your MCP client launches the server directly via standard input/output.

#### Claude Code
```bash
claude mcp add gcp-calculator-mcp -s user -- node /absolute/path/to/calculator-gcp-mcp/dist/index.js --stdio
```

#### Antigravity (`agy`)
```bash
agy mcp add gcp-calculator-mcp node /absolute/path/to/calculator-gcp-mcp/dist/index.js --stdio
```

#### Claude Desktop (`claude_desktop_config.json`)
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gcp-calculator-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/calculator-gcp-mcp/dist/index.js", "--stdio"]
    }
  }
}
```

#### Cursor / Windsurf / Antigravity IDE (`mcp_config.json`)
```json
{
  "mcpServers": {
    "gcp-calculator-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/calculator-gcp-mcp/dist/index.js", "--stdio"]
    }
  }
}
```

---

### 3. Option B — Remote / Local HTTP Mode (Streamable HTTP)

Start the stateless HTTP server locally:

```bash
npm start
# MCP endpoint: http://localhost:8080/mcp
# Health check: http://localhost:8080/health
```

#### Connect MCP Clients over HTTP

**Claude Code:**
```bash
claude mcp add --transport http gcp-calculator-mcp http://localhost:8080/mcp -s user
```

**Antigravity:**
```bash
agy mcp add gcp-calculator-mcp http://localhost:8080/mcp
```

**Claude.ai / Claude Desktop (Custom Connector):**
Go to **Settings → Connectors → Add custom connector** and enter your server URL (e.g., `https://your-service.run.app/mcp`).

---

### 4. Option C — Docker & Docker Compose

Run the server in a minimal Alpine Node.js 20 container:

```bash
docker compose up --build -d
```

- **MCP Endpoint:** `http://localhost:8085/mcp`
- **Health Check:** `http://localhost:8085/health`

Quick verification:
```bash
curl -s http://localhost:8085/health
```

---

### 5. Option D — Deploy to Google Cloud Run (`Makefile`)

The HTTP server is completely stateless (`sessionIdGenerator: undefined`) and scales from `0` to `N` instances on Google Cloud Run.

```bash
gcloud auth login

# 1. Enable APIs, create Artifact Registry repo and service accounts (idempotent)
make setup PROJECT_ID=your-gcp-project REGION=us-central1

# 2. Build container image in Cloud Build and deploy to Cloud Run
make deploy PROJECT_ID=your-gcp-project REGION=us-central1

# 3. Verify /health and POST /mcp tools/list
make check PROJECT_ID=your-gcp-project REGION=us-central1
```

---

## Configuration (Environment Variables)

All environment variables are **optional** (only used in HTTP mode):

| Variable | Default | Description |
| :--- | :--- | :--- |
| `PORT` | `8080` | HTTP listening port |
| `PUBLIC_URL` | *(inferred from request)* | Public base URL displayed on the HTML landing page (without trailing slash) |
| `TRUST_PROXY` | `1` | Express `trust proxy` hop count (Cloud Run = `1`) |
| `MCP_LOG` | `1` | Set to `0` to disable per-request structured logging |

---

## Testing & Development

```bash
# Run in watch/dev mode (TypeScript directly via tsx)
npm run dev

# Unit tests for the HTTP server (no external network calls)
npm test

# End-to-end integration tests for all 6 tools against the live GCP Calculator API
npm run test:integration

# Advanced multi-service estimation scenarios
npm run test:scenarios
```

---

## Contributing

Contributions, bug reports, and pull requests are welcome!

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Run `npm run build && npm test`
4. Open a Pull Request

---

## License

Distributed under the **MIT License**. See [LICENSE](LICENSE) for more information.