gcp-calculator-mcp
by carlosrgomes
README.md
# Google Cloud Pricing Calculator MCP Server (`gcp-calculator-mcp`)
[](LICENSE)
[](https://nodejs.org/)
[](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`)

### Cost Estimate Summary (`previewUrl`)

---
## 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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues