README.md
MCP server for Google Cloud — Cloud Build, Cloud Run, and more.
@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 |
Tools (10)
gcloud_whoamiReturns current GCP project, authenticated identity, and available permissions.gcloud_list_buildsList Cloud Build builds with optional filters for status, trigger, and branch.gcloud_get_buildGet full build details including steps, substitutions, and per-step timing.gcloud_get_build_logsFetch build logs from Cloud Logging with step filtering and line limits.gcloud_get_serviceGet full Cloud Run service details including URL, env vars, resource limits, scaling, and traffic splits.gcloud_list_revisionsList Cloud Run revisions for a service.gcloud_list_servicesList Cloud Run services in a region.gcloud_get_service_logsFetch Cloud Run service logs with severity, time, and revision filters.gcloud_list_triggersList Cloud Build triggers in a project.gcloud_get_triggerGet full Cloud Build trigger configuration.Environment Variables
GOOGLE_CLOUD_PROJECTrequiredThe GCP project ID to manage resources in.Configuration
claude_desktop_config.json
{"mcpServers": {"gcloud-mcp": {"command": "npx", "args": ["-y", "@prmichaelsen/gcloud-mcp"], "env": {"GOOGLE_CLOUD_PROJECT": "your-project-id"}}}}Try it
→List all Cloud Run services in my current project and show me their URLs.
→Get the logs for the latest build of my application to debug why it failed.
→Show me the configuration details for my production Cloud Build trigger.
→List the last 5 revisions for the 'api-service' Cloud Run service.