Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/iam/tools.ts:468-470 (registration)

  Registers the 'gcp-iam-analyse-permission-gaps' tool on the MCP server instance.
  // Tool to analyse permission gaps for a specific resource and operation server.registerTool( "gcp-iam-analyse-permission-gaps",
• src/services/iam/tools.ts:471-490 (schema)

  Defines the input schema for the tool using Zod, including optional project ID, array of required permissions, and optional operation description.
  { title: "Analyse Permission Gaps", description: "Compare current permissions against required permissions for specific operations and identify gaps", inputSchema: { project: z .string() .optional() .describe("Project ID (defaults to current project)"), requiredPermissions: z .array(z.string()) .describe("List of permissions required for the intended operation"), operationDescription: z .string() .optional() .describe( "Description of the operation being attempted (for context)", ), }, },
• src/services/iam/tools.ts:491-614 (handler)

  Executes the tool logic: retrieves project ID, tests IAM permissions via GCP API, identifies gaps between required and granted permissions, and outputs a comprehensive Markdown analysis including suggestions for roles.
  async ({ project, requiredPermissions, operationDescription }) => { try { const projectId = project || (await getProjectId()); const resourceManager = getResourceManagerClient(); const [response] = await resourceManager.testIamPermissions({ resource: `projects/${projectId}`, permissions: requiredPermissions, }); const grantedPermissions = response.permissions || []; const missingPermissions = requiredPermissions.filter( (p) => !grantedPermissions.includes(p), ); let result = `# Permission Gap Analysis\n\n`; result += `**Project:** ${projectId}\n`; if (operationDescription) { result += `**Operation:** ${operationDescription}\n`; } result += `**Total Required Permissions:** ${requiredPermissions.length}\n\n`; // Overall status const hasAllPermissions = missingPermissions.length === 0; result += `## 🎯 Status: ${hasAllPermissions ? "✅ AUTHORISED" : "❌ INSUFFICIENT PERMISSIONS"}\n\n`; if (hasAllPermissions) { result += `✅ You have all required permissions for this operation.\n\n`; } else { result += `❌ Missing ${missingPermissions.length} permission(s). Operation will likely fail.\n\n`; } // Detailed breakdown result += `## Permission Analysis\n\n`; result += `### ✅ Granted Permissions (${grantedPermissions.length})\n\n`; if (grantedPermissions.length > 0) { grantedPermissions.forEach((permission) => { result += `- ${permission}\n`; }); } else { result += `*No permissions granted*\n`; } result += `\n### ❌ Missing Permissions (${missingPermissions.length})\n\n`; if (missingPermissions.length > 0) { missingPermissions.forEach((permission) => { result += `- ${permission}\n`; }); } else { result += `*No missing permissions*\n`; } // Recommendations if (missingPermissions.length > 0) { result += `\n## 📋 Recommendations\n\n`; result += `1. **Contact your GCP administrator** to request the missing permissions\n`; result += `2. **Use predefined roles** that include these permissions:\n`; // Suggest some common roles that might contain these permissions const suggestedRoles = []; if (missingPermissions.some((p) => p.startsWith("compute."))) { suggestedRoles.push( "roles/compute.admin", "roles/compute.instanceAdmin", ); } if (missingPermissions.some((p) => p.startsWith("storage."))) { suggestedRoles.push( "roles/storage.admin", "roles/storage.objectAdmin", ); } if (missingPermissions.some((p) => p.startsWith("run."))) { suggestedRoles.push("roles/run.admin", "roles/run.developer"); } if (missingPermissions.some((p) => p.startsWith("container."))) { suggestedRoles.push( "roles/container.admin", "roles/container.developer", ); } if (missingPermissions.some((p) => p.startsWith("iam."))) { suggestedRoles.push( "roles/iam.serviceAccountUser", "roles/iam.serviceAccountAdmin", ); } if (suggestedRoles.length > 0) { suggestedRoles.forEach((role) => { result += ` - ${role}\n`; }); } else { result += ` - Contact administrator for custom role assignment\n`; } result += `3. **Create a custom role** with exactly these permissions if predefined roles are too broad\n`; } return { content: [ { type: "text", text: result, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; logger.error(`Error analysing permission gaps: ${errorMessage}`); return { content: [ { type: "text", text: `# Error Analysing Permission Gaps\n\nFailed to analyse permissions: ${errorMessage}\n\nPlease ensure the project ID is correct and accessible.`, }, ], isError: true, }; } },