remove_group_members

Remove specified users from a ServiceNow group to manage access permissions and group membership effectively.

Instructions

Remove members from an existing group in ServiceNow

Input Schema

TableJSON Schema

Name	Required	Description	Default
`group_id`	Yes	Group ID or sys_id
`members`	Yes	List of user sys_ids or usernames to remove as members

Implementation Reference

src/servicenow_mcp/tools/user_tools.py:814-897 (handler)

The core handler function implementing the tool logic: iterates over members, resolves user sys_ids if needed, queries for sys_user_grmember records matching the group and user, and deletes them.

def remove_group_members(
    config: ServerConfig,
    auth_manager: AuthManager,
    params: RemoveGroupMembersParams,
) -> GroupResponse:
    """
    Remove members from a group in ServiceNow.

    Args:
        config: Server configuration.
        auth_manager: Authentication manager.
        params: Parameters for removing members from the group.

    Returns:
        Response with the result of the operation.
    """
    success = True
    failed_members = []

    for member in params.members:
        # Get user ID if username is provided
        user_id = member
        if not member.startswith("sys_id:"):
            user = get_user(config, auth_manager, GetUserParams(user_name=member))
            if not user.get("success"):
                user = get_user(config, auth_manager, GetUserParams(email=member))

            if user.get("success"):
                user_id = user.get("user", {}).get("sys_id")
            else:
                success = False
                failed_members.append(member)
                continue

        # Find and delete the group membership
        api_url = f"{config.api_url}/table/sys_user_grmember"
        query_params = {
            "sysparm_query": f"group={params.group_id}^user={user_id}",
            "sysparm_limit": "1",
        }

        try:
            # First find the membership record
            response = requests.get(
                api_url,
                params=query_params,
                headers=auth_manager.get_headers(),
                timeout=config.timeout,
            )
            response.raise_for_status()

            result = response.json().get("result", [])
            if not result:
                success = False
                failed_members.append(member)
                continue

            # Then delete the membership record
            membership_id = result[0].get("sys_id")
            delete_url = f"{api_url}/{membership_id}"

            response = requests.delete(
                delete_url,
                headers=auth_manager.get_headers(),
                timeout=config.timeout,
            )
            response.raise_for_status()

        except requests.RequestException as e:
            logger.error(f"Failed to remove member '{member}' from group: {e}")
            success = False
            failed_members.append(member)

    if failed_members:
        message = f"Some members could not be removed from the group: {', '.join(failed_members)}"
    else:
        message = "All members removed from the group successfully"

    return GroupResponse(
        success=success,
        message=message,
        group_id=params.group_id,
    )

src/servicenow_mcp/tools/user_tools.py:114-121 (schema)

Pydantic BaseModel defining the input schema for the tool: requires group_id (str) and members (list of str, sys_ids or usernames).

class RemoveGroupMembersParams(BaseModel):
    """Parameters for removing members from a group."""

    group_id: str = Field(..., description="Group ID or sys_id")
    members: List[str] = Field(
        ..., description="List of user sys_ids or usernames to remove as members"
    )

src/servicenow_mcp/utils/tool_utils.py:822-828 (registration)
Tool registration in the central get_tool_definitions() function's dictionary, associating the tool name with its handler (aliased import), params model, return type hint, description, and serialization method.
```
"remove_group_members": (
    remove_group_members_tool,
    RemoveGroupMembersParams,
    Dict[str, Any],  # Expects dict
    "Remove members from an existing group in ServiceNow",
    "raw_dict",
),
```

ServiceNow MCP Server