@prmichaelsen/gcloud-mcp

MCP server for Google Cloud — Cloud Build, Cloud Run, Artifact Registry, and Secret Manager. 17 tools for listing, inspecting, deploying, and managing GCP resources.

Installation

npm install @prmichaelsen/gcloud-mcp

Prerequisites

• Node.js 20+
• GCP Application Default Credentials: gcloud auth application-default login
• Required IAM roles: roles/cloudbuild.builds.viewer, roles/logging.viewer, roles/run.viewer, roles/artifactregistry.reader, roles/secretmanager.viewer

Usage

Claude Code

claude mcp add -e GOOGLE_CLOUD_PROJECT=your-project-id -- gcloud-mcp node /path/to/dist/server.js

Or via npx (after npm publish):

claude mcp add -e GOOGLE_CLOUD_PROJECT=your-project-id -- gcloud-mcp npx -y @prmichaelsen/gcloud-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gcloud-mcp": {
      "command": "npx",
      "args": ["-y", "@prmichaelsen/gcloud-mcp"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id"
      }
    }
  }
}

Multi-Tenant (mcp-auth)

import { wrapServer, JWTAuthProvider } from '@prmichaelsen/mcp-auth';
import { createServer } from '@prmichaelsen/gcloud-mcp/factory';

const wrapped = wrapServer({
  serverFactory: createServer,
  authProvider: new JWTAuthProvider({
    jwtSecret: process.env.JWT_SECRET!,
  }),
  resourceType: 'gcloud',
  transport: { type: 'sse', port: 3000 },
});

await wrapped.start();

Tools

gcloud_whoami

Returns current GCP project, authenticated identity, and available permissions.

gcloud_list_builds

List Cloud Build builds with optional filters for status, trigger, and branch.

Parameter	Type	Required	Description
projectId	string	No	GCP project ID (defaults to env)
status	string	No	Filter: SUCCESS, FAILURE, WORKING, etc.
triggerId	string	No	Filter by trigger ID
branchName	string	No	Filter by branch
limit	number	No	Max results (default 10, max 100)

gcloud_get_build

Get full build details including steps, substitutions, and per-step timing.

Parameter	Type	Required	Description
buildId	string	Yes	Cloud Build build ID
projectId	string	No	GCP project ID

gcloud_get_build_logs

Fetch build logs from Cloud Logging with step filtering and line limits.

Parameter	Type	Required	Description
buildId	string	Yes	Cloud Build build ID
projectId	string	No	GCP project ID
stepName	string	No	Filter by step name
limit	number	No	Max lines (default 100)
tail	boolean	No	Return last N lines

gcloud_get_service

Get full Cloud Run service details including URL, env vars, resource limits, scaling, and traffic splits.

Parameter	Type	Required	Description
serviceName	string	Yes	Cloud Run service name
region	string	No	GCP region (defaults to env)
projectId	string	No	GCP project ID

gcloud_list_revisions

List Cloud Run revisions for a service. Shows deployment history with image tags and creation times.

Parameter	Type	Required	Description
serviceName	string	Yes	Cloud Run service name
region	string	No	GCP region
projectId	string	No	GCP project ID
limit	number	No	Max revisions (default 10, max 50)

gcloud_list_services

List Cloud Run services in a region.

Parameter	Type	Required	Description
region	string	No	GCP region (defaults to env)
projectId	string	No	GCP project ID

gcloud_get_service_logs

Fetch Cloud Run service logs with severity, time, and revision filters.

Parameter	Type	Required	Description
serviceName	string	Yes	Cloud Run service name
region	string	No	GCP region
projectId	string	No	GCP project ID
severity	string	No	Min severity: DEBUG, INFO, WARNING, ERROR, CRITICAL
since	string	No	Time range: "1h", "30m", "2d" (default "1h")
revision	string	No	Filter by revision
limit	number	No	Max entries (default 50, max 500)

gcloud_list_triggers

List Cloud Build triggers in a project.

Parameter	Type	Required	Description
projectId	string	No	GCP project ID

gcloud_get_trigger

Get full Cloud Build trigger configuration including repo, branch filter, build steps, and substitutions.

Parameter	Type	Required	Description
triggerId	string	Yes	Cloud Build trigger ID
projectId	string	No	GCP project ID

gcloud_list_jobs

List Cloud Run Jobs in a region.

Parameter	Type	Required	Description
region	string	No	GCP region (defaults to env)
projectId	string	No	GCP project ID

gcloud_get_job_execution

Get Cloud Run Job execution details or list recent executions.

Parameter	Type	Required	Description
jobName	string	Yes	Cloud Run Job name
executionName	string	No	Specific execution name (omit to list recent)
region	string	No	GCP region
projectId	string	No	GCP project ID
limit	number	No	Max executions to list (default 5, max 20)

gcloud_list_artifacts

List Docker images in an Artifact Registry repository, or list repositories.

Parameter	Type	Required	Description
repository	string	No	Repository name (omit to list repos)
region	string	No	GCP region
projectId	string	No	GCP project ID
limit	number	No	Max images (default 10, max 50)

gcloud_list_secrets

List Secret Manager secret names (NOT values).

Parameter	Type	Required	Description
projectId	string	No	GCP project ID
filter	string	No	Filter string (e.g. "name:remember-")

gcloud_run_trigger

Manually trigger a Cloud Build. Returns the build ID of the triggered build.

Parameter	Type	Required	Description
triggerId	string	Yes	Cloud Build trigger ID
branchName	string	No	Branch to build from
tagName	string	No	Tag to build from
substitutions	object	No	Key-value substitution variables
projectId	string	No	GCP project ID

gcloud_deploy_service

Deploy a new revision to a Cloud Run service by updating the container image.

Parameter	Type	Required	Description
serviceName	string	Yes	Cloud Run service name
image	string	Yes	Container image (e.g. "gcr.io/project/image:tag")
region	string	No	GCP region
projectId	string	No	GCP project ID
env	object	No	Environment variables to set (key-value)
memory	string	No	Memory limit (e.g. "512Mi")
cpu	string	No	CPU limit (e.g. "1")
minInstances	number	No	Min instances
maxInstances	number	No	Max instances

gcloud_set_traffic

Set traffic splitting between Cloud Run revisions for canary deployments and rollbacks.

Parameter	Type	Required	Description
serviceName	string	Yes	Cloud Run service name
traffic	array	Yes	Traffic entries: [{revision, percent}]. Use "LATEST" for latest. Must sum to 100.
region	string	No	GCP region
projectId	string	No	GCP project ID

Environment Variables

Variable	Required	Description
GOOGLE_CLOUD_PROJECT	Yes	Default GCP project ID
GOOGLE_CLOUD_REGION	No	Default Cloud Run region (default: us-central1)
LOG_LEVEL	No	Server log level: debug, info, warn, error

Development

npm install
npm run build
npm run dev      # watch mode
npm run typecheck

License

MIT