get_role_permissions

Retrieve detailed IAM role information, including permissions, for roles in GCP. Specify a role name or project ID for custom roles to analyze access controls systematically.

Instructions

    Get detailed information about an IAM role, including its permissions.
    
    Args:
        role_name: The name of the role (e.g., "roles/compute.admin" or "projects/my-project/roles/myCustomRole")
        project_id: Optional project ID for custom roles. Not needed if role_name is fully qualified.
    
    Returns:
        Detailed information about the IAM role

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_id`	No
`role_name`	Yes

Implementation Reference

src/gcp_mcp/gcp_modules/iam/tools.py:123-173 (handler)

The core handler function for the 'get_role_permissions' MCP tool. It resolves the role name, fetches the role using IAMClient.get_role, extracts details like title, description, permissions list, stage, and ETag, then formats and returns them. Includes input validation via type hints and docstring, and error handling.

    @mcp.tool()
    def get_role_permissions(role_name: str, project_id: Optional[str] = None) -> str:
        """
        Get detailed information about an IAM role, including its permissions.
        
        Args:
            role_name: The name of the role (e.g., "roles/compute.admin" or "projects/my-project/roles/myCustomRole")
            project_id: Optional project ID for custom roles. Not needed if role_name is fully qualified.
        
        Returns:
            Detailed information about the IAM role
        """
        try:
            from google.cloud import iam_v1
            
            # Initialize the IAM client
            client = iam_v1.IAMClient()
            
            # If project_id is provided and role_name doesn't include it, create fully qualified role name
            if project_id and not role_name.startswith("projects/") and not role_name.startswith("roles/"):
                role_name = f"projects/{project_id}/roles/{role_name}"
            elif not role_name.startswith("projects/") and not role_name.startswith("roles/"):
                role_name = f"roles/{role_name}"
            
            # Get role details
            request = iam_v1.GetRoleRequest(name=role_name)
            role = client.get_role(request=request)
            
            details = []
            details.append(f"Name: {role.name}")
            details.append(f"Title: {role.title}")
            details.append(f"Description: {role.description or 'No description'}")
            
            if role.included_permissions:
                permissions_str = "\n".join([f"- {permission}" for permission in role.included_permissions])
                details.append(f"Permissions ({len(role.included_permissions)}):\n{permissions_str}")
            else:
                details.append("Permissions: None")
            
            if hasattr(role, 'stage'):
                details.append(f"Stage: {role.stage}")
            
            if hasattr(role, 'etag'):
                details.append(f"ETag: {role.etag}")
            
            return f"""
IAM Role Details for {role.name}:
{chr(10).join(details)}
"""
        except Exception as e:
            return f"Error getting role permissions: {str(e)}"

src/gcp_mcp/server.py:35-36 (registration)
Top-level registration call for the IAM tools module in the MCP server, which includes the get_role_permissions tool. This invokes the module's register_tools function to add all IAM-related tools to the MCP instance.
```
# Register IAM tools
iam_tools.register_tools(mcp)
```
src/gcp_mcp/server.py:7-7 (registration)
Import of the IAM tools module aliased as iam_tools, enabling its register_tools to be called for registering get_role_permissions and other IAM tools.
```
from .gcp_modules.iam import tools as iam_tools
```

GCP MCP