Skip to content

Getting Started

Jump to bottom
Anna edited this page Jun 26, 2026 · 2 revisions

Getting Started & Module Configuration

Prerequisites

  • Go 1.22+ — install (only needed if installing via Go toolchain or building from source)
  • A GCP project with billing enabled
  • gcloud CLI — install
  • An MCP-compatible host — Claude Desktop, VS Code with an MCP extension, or any stdio MCP client

Install

Homebrew (macOS / Linux) — recommended

brew install asbrodova/tap/aura-tracker-gcp

macOS Gatekeeper: On first run macOS may block the binary with a "cannot be opened" warning. Fix with either:

  • xattr -d com.apple.quarantine $(which aura-tracker-gcp) in your terminal, then restart Claude Desktop.
  • System Settings → Privacy & Security → scroll down to aura-tracker-gcp → click Allow Anyway, then restart Claude Desktop.

Direct binary download (all platforms)

Download the archive for your platform from the latest release:

# macOS Apple Silicon
curl -L https://github.com/asbrodova/aura-tracker-gcp/releases/latest/download/aura-tracker-gcp_darwin_arm64.tar.gz \
  | tar xz && sudo mv aura-tracker-gcp /usr/local/bin/

# macOS Intel
curl -L https://github.com/asbrodova/aura-tracker-gcp/releases/latest/download/aura-tracker-gcp_darwin_amd64.tar.gz \
  | tar xz && sudo mv aura-tracker-gcp /usr/local/bin/

# Linux amd64
curl -L https://github.com/asbrodova/aura-tracker-gcp/releases/latest/download/aura-tracker-gcp_linux_amd64.tar.gz \
  | tar xz && sudo mv aura-tracker-gcp /usr/local/bin/

Go toolchain

go install github.com/asbrodova/aura-tracker-gcp/cmd/aura-tracker-gcp@latest

Docker

docker run --rm \
  -e GCP_PROJECT_ID=my-project \
  -v "$HOME/.config/gcloud/application_default_credentials.json:/creds.json:ro" \
  -e GOOGLE_APPLICATION_CREDENTIALS=/creds.json \
  ghcr.io/asbrodova/aura-tracker-gcp:latest

Build from source

git clone https://github.com/asbrodova/aura-tracker-gcp.git
cd aura-tracker-gcp
go build ./...

Authenticate with GCP

The server uses Application Default Credentials (ADC). The fastest option for local development:

gcloud auth application-default login

Use a Service Account (recommended for production)

Create a dedicated service account with least-privilege roles (see Security and Safety):

# One-liner: use the bundled setup script
PROJECT_ID=my-project bash scripts/setup-iam.sh

# Or manually
gcloud iam service-accounts create aura-tracker \
  --display-name="Aura Tracker GCP" \
  --project=MY_PROJECT

gcloud projects add-iam-policy-binding MY_PROJECT \
  --member="serviceAccount:aura-tracker@MY_PROJECT.iam.gserviceaccount.com" \
  --role="roles/run.viewer"
# ... repeat for each role in the IAM guide

gcloud iam service-accounts keys create key.json \
  --iam-account=aura-tracker@MY_PROJECT.iam.gserviceaccount.com

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Connect to Claude Desktop

Add to claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "aura-tracker-gcp": {
      "command": "/absolute/path/to/aura-tracker-gcp",
      "env": {
        "GCP_PROJECT_ID": "my-project-id"
      }
    }
  }
}

Use the absolute path to the binary — relative paths and ~ are not expanded. Restart Claude Desktop after saving.

Your First Query

Once connected, try these in your LLM:

List my Cloud Run services in project my-project

What is the Aura Score summary for project my-project?

Show me recent ERROR logs for project my-project

If you get a permissions error, verify your setup:

Test my IAM permissions for project my-project

This calls gcp_iam_test_permissions and returns a per-permission allowed: true/false breakdown. Compare against Security and Safety.

Why Module Selection Matters

By default, all 26 modules start and register all 69 tool definitions. Every tool schema is sent to the LLM as part of its context window on each request — this is how MCP works.

That has a real cost:

  • More tool schemas = more tokens consumed per prompt
  • More tokens = slower first-token latency
  • More tokens = higher cost per call on hosted models with per-token pricing

The fix is the --modules flag. Load only the tools relevant to what you're doing right now. For a Cloud Run debugging session you don't need GKE Mesh, Spanner, or Supply Chain schemas in every prompt.

When a module is excluded, the server also skips initializing that module's GCP SDK client — narrowing the OAuth token scope and reducing startup memory.

Selecting Modules

Pass a comma-separated list to --modules:

# Only load Cloud Run and Pub/Sub tools
GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules cloudrun,pubsub

# Load all modules (default — good for exploration)
GCP_PROJECT_ID=my-project ./aura-tracker-gcp

# Zero tools — MCP Resources and Prompts still available
GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules none

Common Module Combinations

Pick the combination that matches your current task. These are starting points — mix and match as needed.

Goal --modules value
Serverless event-driven stack cloudrun,functions,pubsub,eventarc,scheduler,workflows,tasks
GKE investigation gke,gke_workloads,gke_mesh,monitoring,logging
Health & efficiency audit aura,monitoring,cloudrun
Security & IAM review iam,secretmanager,logging
Cost optimization aura,monitoring,bigquery,cloudsql
Architecture export archgraph,serverlessgraph,topology
Data stores cloudsql,datastores,storage
Observability gap analysis coverage,monitoring,logging,cloudrun

Tip: for a focused debugging session, start narrow. It's easy to restart the server with additional modules if you need them.

Connect to Other MCP Hosts

The server uses stdio transport by default: reads JSON-RPC from stdin, writes to stdout. Any MCP-compatible host works.

For HTTP/SSE mode (shared/remote access or Cloud Run deployment), see Configure Your Environment.

Next Steps

Topic Page
All environment variables Configure Your Environment
Safety defaults and HITL details Safety & Cost Safeguards
PII scrubbing setup Security and Safety
All module names and what they expose Module Reference
Aura Score explained Aura Score
Built-in prompt workflows Built-in Prompts and Workflows

Clone this wiki locally