Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/iam/tools.ts:278-405 (handler)

  The core handler function that implements the tool logic. It fetches the project ID, retrieves the deployment permission set for the specified service, tests the user's permissions using Google's IAM API, and generates a comprehensive Markdown report detailing granted and missing permissions for deployment.
  async ({ service, project, includeOptional }) => { try { const projectId = project || (await getProjectId()); const resourceManager = getResourceManagerClient(); const permissionSet = getDeploymentPermissionSet(service); if (!permissionSet) { const availableServices = getAllDeploymentPermissionSets() .map((s) => s.service.toLowerCase()) .join(", "); return { content: [ { type: "text", text: `# Invalid Service\n\nService "${service}" not found.\n\n**Available services:** ${availableServices}`, }, ], isError: true, }; } const allPermissions = [...permissionSet.requiredPermissions]; if (includeOptional && permissionSet.optionalPermissions) { allPermissions.push(...permissionSet.optionalPermissions); } const [response] = await resourceManager.testIamPermissions({ resource: `projects/${projectId}`, permissions: allPermissions, }); const grantedPermissions = response.permissions || []; const missingRequired = permissionSet.requiredPermissions.filter( (p) => !grantedPermissions.includes(p), ); const missingOptional = includeOptional && permissionSet.optionalPermissions ? permissionSet.optionalPermissions.filter( (p) => !grantedPermissions.includes(p), ) : []; let result = `# ${permissionSet.service} Deployment Validation\n\n`; result += `**Project:** ${projectId}\n`; result += `**Service:** ${permissionSet.service}\n`; result += `**Description:** ${permissionSet.description}\n\n`; // Overall status const canDeploy = missingRequired.length === 0; result += `## 🎯 Deployment Status: ${canDeploy ? "✅ READY" : "❌ BLOCKED"}\n\n`; if (canDeploy) { result += `✅ You have all required permissions to deploy ${permissionSet.service}\n\n`; } else { result += `❌ Missing ${missingRequired.length} required permission(s) for ${permissionSet.service} deployment\n\n`; } // Required permissions analysis result += `## Required Permissions (${permissionSet.requiredPermissions.length})\n\n`; permissionSet.requiredPermissions.forEach((permission) => { const status = grantedPermissions.includes(permission) ? "✅" : "❌"; result += `${status} ${permission}\n`; }); // Optional permissions analysis (if requested) if ( includeOptional && permissionSet.optionalPermissions && permissionSet.optionalPermissions.length > 0 ) { result += `\n## Optional Permissions (${permissionSet.optionalPermissions.length})\n\n`; permissionSet.optionalPermissions.forEach((permission) => { const status = grantedPermissions.includes(permission) ? "✅" : "❌"; result += `${status} ${permission}\n`; }); } // Common resources if (permissionSet.commonResources.length > 0) { result += `\n## Common Resource Patterns\n\n`; permissionSet.commonResources.forEach((resource) => { result += `- ${resource}\n`; }); } // Summary and next steps result += `\n## Summary\n\n`; result += `- **Required:** ${permissionSet.requiredPermissions.length - missingRequired.length}/${permissionSet.requiredPermissions.length} granted\n`; if (includeOptional && permissionSet.optionalPermissions) { result += `- **Optional:** ${permissionSet.optionalPermissions.length - missingOptional.length}/${permissionSet.optionalPermissions.length} granted\n`; } if (!canDeploy) { result += `\n### ⚠️ Missing Required Permissions\n\n`; missingRequired.forEach((permission) => { result += `- ${permission}\n`; }); result += `\n**Next Steps:** Contact your GCP administrator to grant the missing required permissions.\n`; } return { content: [ { type: "text", text: result, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; logger.error( `Error validating deployment permissions: ${errorMessage}`, ); return { content: [ { type: "text", text: `# Error Validating Deployment Permissions\n\nFailed to validate permissions for ${service}: ${errorMessage}\n\nPlease ensure the project ID is correct and accessible.`, }, ], isError: true, }; } },
• src/services/iam/tools.ts:262-276 (schema)

  Zod-based input schema defining the tool's parameters: service (string, required), project (optional string), includeOptional (optional boolean, defaults to false). Also includes title and description in the surrounding object.
  inputSchema: { service: z .string() .describe( "GCP service to validate (cloud-run, gke, compute-engine, cloud-functions, app-engine, cloud-storage, cloud-sql)", ), project: z .string() .optional() .describe("Project ID (defaults to current project)"), includeOptional: z .boolean() .default(false) .describe("Include optional permissions in the validation"), },
• src/services/iam/tools.ts:256-406 (registration)

  The server.registerTool call that registers the tool with the MCP server, providing name, schema/config, and handler function.
  server.registerTool( "gcp-iam-validate-deployment-permissions", { title: "Validate Deployment Permissions", description: "Check if current caller has required permissions for deploying to common GCP services", inputSchema: { service: z .string() .describe( "GCP service to validate (cloud-run, gke, compute-engine, cloud-functions, app-engine, cloud-storage, cloud-sql)", ), project: z .string() .optional() .describe("Project ID (defaults to current project)"), includeOptional: z .boolean() .default(false) .describe("Include optional permissions in the validation"), }, }, async ({ service, project, includeOptional }) => { try { const projectId = project || (await getProjectId()); const resourceManager = getResourceManagerClient(); const permissionSet = getDeploymentPermissionSet(service); if (!permissionSet) { const availableServices = getAllDeploymentPermissionSets() .map((s) => s.service.toLowerCase()) .join(", "); return { content: [ { type: "text", text: `# Invalid Service\n\nService "${service}" not found.\n\n**Available services:** ${availableServices}`, }, ], isError: true, }; } const allPermissions = [...permissionSet.requiredPermissions]; if (includeOptional && permissionSet.optionalPermissions) { allPermissions.push(...permissionSet.optionalPermissions); } const [response] = await resourceManager.testIamPermissions({ resource: `projects/${projectId}`, permissions: allPermissions, }); const grantedPermissions = response.permissions || []; const missingRequired = permissionSet.requiredPermissions.filter( (p) => !grantedPermissions.includes(p), ); const missingOptional = includeOptional && permissionSet.optionalPermissions ? permissionSet.optionalPermissions.filter( (p) => !grantedPermissions.includes(p), ) : []; let result = `# ${permissionSet.service} Deployment Validation\n\n`; result += `**Project:** ${projectId}\n`; result += `**Service:** ${permissionSet.service}\n`; result += `**Description:** ${permissionSet.description}\n\n`; // Overall status const canDeploy = missingRequired.length === 0; result += `## 🎯 Deployment Status: ${canDeploy ? "✅ READY" : "❌ BLOCKED"}\n\n`; if (canDeploy) { result += `✅ You have all required permissions to deploy ${permissionSet.service}\n\n`; } else { result += `❌ Missing ${missingRequired.length} required permission(s) for ${permissionSet.service} deployment\n\n`; } // Required permissions analysis result += `## Required Permissions (${permissionSet.requiredPermissions.length})\n\n`; permissionSet.requiredPermissions.forEach((permission) => { const status = grantedPermissions.includes(permission) ? "✅" : "❌"; result += `${status} ${permission}\n`; }); // Optional permissions analysis (if requested) if ( includeOptional && permissionSet.optionalPermissions && permissionSet.optionalPermissions.length > 0 ) { result += `\n## Optional Permissions (${permissionSet.optionalPermissions.length})\n\n`; permissionSet.optionalPermissions.forEach((permission) => { const status = grantedPermissions.includes(permission) ? "✅" : "❌"; result += `${status} ${permission}\n`; }); } // Common resources if (permissionSet.commonResources.length > 0) { result += `\n## Common Resource Patterns\n\n`; permissionSet.commonResources.forEach((resource) => { result += `- ${resource}\n`; }); } // Summary and next steps result += `\n## Summary\n\n`; result += `- **Required:** ${permissionSet.requiredPermissions.length - missingRequired.length}/${permissionSet.requiredPermissions.length} granted\n`; if (includeOptional && permissionSet.optionalPermissions) { result += `- **Optional:** ${permissionSet.optionalPermissions.length - missingOptional.length}/${permissionSet.optionalPermissions.length} granted\n`; } if (!canDeploy) { result += `\n### ⚠️ Missing Required Permissions\n\n`; missingRequired.forEach((permission) => { result += `- ${permission}\n`; }); result += `\n**Next Steps:** Contact your GCP administrator to grant the missing required permissions.\n`; } return { content: [ { type: "text", text: result, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; logger.error( `Error validating deployment permissions: ${errorMessage}`, ); return { content: [ { type: "text", text: `# Error Validating Deployment Permissions\n\nFailed to validate permissions for ${service}: ${errorMessage}\n\nPlease ensure the project ID is correct and accessible.`, }, ], isError: true, }; } }, );
• src/services/iam/types.ts:231-395 (helper)

  Predefined permission sets for common GCP deployment services. Maps service names to required/optional permissions and resource patterns, used by the handler to determine what permissions to test.
  export const DEPLOYMENT_PERMISSION_SETS: Record< string, DeploymentPermissionSet > = { "cloud-run": { service: "Cloud Run", description: "Deploy and manage Cloud Run services", requiredPermissions: [ "run.services.create", "run.services.update", "run.services.get", "run.services.list", "run.services.delete", "run.revisions.get", "run.revisions.list", "iam.serviceAccounts.actAs", ], optionalPermissions: [ "run.services.setIamPolicy", "run.services.getIamPolicy", "cloudsql.instances.connect", "secretmanager.versions.access", ], commonResources: [ "projects/{project}/locations/{location}/services/{service}", ], }, gke: { service: "Google Kubernetes Engine", description: "Deploy and manage GKE clusters and workloads", requiredPermissions: [ "container.clusters.create", "container.clusters.update", "container.clusters.get", "container.clusters.list", "container.clusters.delete", "container.operations.get", "container.operations.list", "compute.instances.get", "compute.instances.list", "iam.serviceAccounts.actAs", ], optionalPermissions: [ "container.clusters.getCredentials", "compute.networks.get", "compute.subnetworks.get", "logging.logEntries.create", "monitoring.metricDescriptors.create", ], commonResources: [ "projects/{project}/locations/{location}/clusters/{cluster}", ], }, "compute-engine": { service: "Compute Engine", description: "Deploy and manage Compute Engine instances", requiredPermissions: [ "compute.instances.create", "compute.instances.delete", "compute.instances.get", "compute.instances.list", "compute.instances.start", "compute.instances.stop", "compute.disks.create", "compute.disks.use", "compute.networks.use", "compute.subnetworks.use", "iam.serviceAccounts.actAs", ], optionalPermissions: [ "compute.instances.setMetadata", "compute.instances.setTags", "compute.firewalls.create", "compute.addresses.create", ], commonResources: ["projects/{project}/zones/{zone}/instances/{instance}"], }, "cloud-functions": { service: "Cloud Functions", description: "Deploy and manage Cloud Functions", requiredPermissions: [ "cloudfunctions.functions.create", "cloudfunctions.functions.update", "cloudfunctions.functions.get", "cloudfunctions.functions.list", "cloudfunctions.functions.delete", "cloudfunctions.operations.get", "iam.serviceAccounts.actAs", ], optionalPermissions: [ "cloudfunctions.functions.setIamPolicy", "cloudfunctions.functions.getIamPolicy", "storage.buckets.get", "storage.objects.create", ], commonResources: [ "projects/{project}/locations/{location}/functions/{function}", ], }, "app-engine": { service: "App Engine", description: "Deploy and manage App Engine applications", requiredPermissions: [ "appengine.applications.create", "appengine.applications.update", "appengine.applications.get", "appengine.versions.create", "appengine.versions.update", "appengine.versions.get", "appengine.versions.list", "appengine.services.get", "appengine.services.list", ], optionalPermissions: [ "appengine.versions.delete", "appengine.instances.get", "appengine.instances.list", "storage.buckets.get", "storage.objects.create", ], commonResources: [ "projects/{project}/services/{service}/versions/{version}", ], }, "cloud-storage": { service: "Cloud Storage", description: "Manage Cloud Storage buckets and objects", requiredPermissions: [ "storage.buckets.create", "storage.buckets.get", "storage.buckets.list", "storage.objects.create", "storage.objects.get", "storage.objects.list", ], optionalPermissions: [ "storage.buckets.delete", "storage.objects.delete", "storage.buckets.setIamPolicy", "storage.buckets.getIamPolicy", ], commonResources: ["projects/{project}/buckets/{bucket}"], }, "cloud-sql": { service: "Cloud SQL", description: "Deploy and manage Cloud SQL instances", requiredPermissions: [ "cloudsql.instances.create", "cloudsql.instances.update", "cloudsql.instances.get", "cloudsql.instances.list", "cloudsql.instances.connect", "cloudsql.databases.create", "cloudsql.databases.get", "cloudsql.databases.list", ], optionalPermissions: [ "cloudsql.instances.delete", "cloudsql.users.create", "cloudsql.users.list", "cloudsql.backupRuns.create", ], commonResources: ["projects/{project}/instances/{instance}"], }, };
• src/services/iam/types.ts:400-404 (helper)

  Helper function to retrieve the permission set for a given service name from DEPLOYMENT_PERMISSION_SETS, used in the handler.
  export function getDeploymentPermissionSet( serviceName: string, ): DeploymentPermissionSet | null { return DEPLOYMENT_PERMISSION_SETS[serviceName.toLowerCase()] || null; }