Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/iam/tools.ts:42-91 (handler)

  Executes the tool logic: gets the current or specified project ID, fetches the IAM policy using Google Cloud Resource Manager client with specified version, formats it using formatIamPolicy helper, and returns markdown text response. Handles missing policy and errors with user-friendly messages.

    async ({ project, requestedPolicyVersion }) => {
      try {
        const projectId = project || (await getProjectId());
        const resourceManager = getResourceManagerClient();
  
        const [policy] = await resourceManager.getIamPolicy({
          resource: `projects/${projectId}`,
          options: {
            requestedPolicyVersion,
          },
        });
  
        if (!policy) {
          return {
            content: [
              {
                type: "text",
                text: `# Project IAM Policy Not Found\n\nNo IAM policy found for project: ${projectId}`,
              },
            ],
          };
        }
  
        const formattedPolicy = formatIamPolicy(policy as IamPolicy);
  
        return {
          content: [
            {
              type: "text",
              text: `# Project IAM Policy\n\nProject: ${projectId}\nPolicy Version: ${requestedPolicyVersion}\n\n${formattedPolicy}`,
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : "Unknown error";
        logger.error(`Error getting project IAM policy: ${errorMessage}`);
  
        return {
          content: [
            {
              type: "text",
              text: `# Error Getting Project IAM Policy\n\nFailed to retrieve IAM policy for project "${project || "current"}": ${errorMessage}\n\nPlease ensure:\n- The project ID is correct\n- You have the required permissions (resourcemanager.projects.getIamPolicy)\n- The project exists and is accessible`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/services/iam/tools.ts:26-41 (schema)

  Input schema definition using Zod validators for optional project ID and policy version (1-3, default 3). Title and description provided for the tool.

  {
    title: "Get Project IAM Policy",
    description: "Retrieve the IAM policy for a Google Cloud project",
    inputSchema: {
      project: z
        .string()
        .optional()
        .describe("Project ID (defaults to current project)"),
      requestedPolicyVersion: z
        .number()
        .min(1)
        .max(3)
        .default(3)
        .describe("The policy format version (1, 2, or 3)"),
    },
  },

• src/services/iam/tools.ts:25-91 (registration)

  Registers the tool 'gcp-iam-get-project-policy' on the MCP server within the registerIamTools function, providing schema and handler.

    "gcp-iam-get-project-policy",
    {
      title: "Get Project IAM Policy",
      description: "Retrieve the IAM policy for a Google Cloud project",
      inputSchema: {
        project: z
          .string()
          .optional()
          .describe("Project ID (defaults to current project)"),
        requestedPolicyVersion: z
          .number()
          .min(1)
          .max(3)
          .default(3)
          .describe("The policy format version (1, 2, or 3)"),
      },
    },
    async ({ project, requestedPolicyVersion }) => {
      try {
        const projectId = project || (await getProjectId());
        const resourceManager = getResourceManagerClient();
  
        const [policy] = await resourceManager.getIamPolicy({
          resource: `projects/${projectId}`,
          options: {
            requestedPolicyVersion,
          },
        });
  
        if (!policy) {
          return {
            content: [
              {
                type: "text",
                text: `# Project IAM Policy Not Found\n\nNo IAM policy found for project: ${projectId}`,
              },
            ],
          };
        }
  
        const formattedPolicy = formatIamPolicy(policy as IamPolicy);
  
        return {
          content: [
            {
              type: "text",
              text: `# Project IAM Policy\n\nProject: ${projectId}\nPolicy Version: ${requestedPolicyVersion}\n\n${formattedPolicy}`,
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : "Unknown error";
        logger.error(`Error getting project IAM policy: ${errorMessage}`);
  
        return {
          content: [
            {
              type: "text",
              text: `# Error Getting Project IAM Policy\n\nFailed to retrieve IAM policy for project "${project || "current"}": ${errorMessage}\n\nPlease ensure:\n- The project ID is correct\n- You have the required permissions (resourcemanager.projects.getIamPolicy)\n- The project exists and is accessible`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/services/iam/types.ts:166-173 (helper)

  Provides a singleton instance of the Google Cloud Resource Manager ProjectsClient, used by the handler to call getIamPolicy.

  export function getResourceManagerClient(): ProjectsClient {
    if (!resourceManagerClientInstance) {
      resourceManagerClientInstance = new ProjectsClient({
        projectId: process.env.GOOGLE_CLOUD_PROJECT,
      });
    }
    return resourceManagerClientInstance;
  }

• src/services/iam/types.ts:181-226 (helper)

  Formats the raw IAM policy into a structured markdown string, including version, bindings with members and conditions, and audit configurations.

  export function formatIamPolicy(policy: IamPolicy): string {
    let result = `## IAM Policy\n\n`;
  
    result += `**Version:** ${policy.version || 1}\n`;
    if (policy.etag) result += `**ETag:** ${policy.etag}\n`;
  
    if (policy.bindings && policy.bindings.length > 0) {
      result += `\n**Policy Bindings:**\n\n`;
  
      policy.bindings.forEach((binding, index) => {
        result += `### Binding ${index + 1}: ${binding.role}\n\n`;
        result += `**Members:**\n`;
        binding.members.forEach((member) => {
          result += `- ${member}\n`;
        });
  
        if (binding.condition) {
          result += `\n**Condition:**\n`;
          if (binding.condition.title)
            result += `- Title: ${binding.condition.title}\n`;
          if (binding.condition.description)
            result += `- Description: ${binding.condition.description}\n`;
          result += `- Expression: \`${binding.condition.expression}\`\n`;
        }
        result += "\n";
      });
    }
  
    if (policy.auditConfigs && policy.auditConfigs.length > 0) {
      result += `**Audit Configurations:**\n\n`;
  
      policy.auditConfigs.forEach((config, index) => {
        result += `### Audit Config ${index + 1}: ${config.service}\n\n`;
        config.auditLogConfigs.forEach((logConfig, logIndex) => {
          result += `**Log Config ${logIndex + 1}:**\n`;
          result += `- Log Type: ${logConfig.logType}\n`;
          if (logConfig.exemptedMembers && logConfig.exemptedMembers.length > 0) {
            result += `- Exempted Members: ${logConfig.exemptedMembers.join(", ")}\n`;
          }
          result += "\n";
        });
      });
    }
  
    return result;
  }