ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/user_tools.py:227-300 (handler)

  The core handler function that builds the update payload and sends a PATCH request to the ServiceNow sys_user table API endpoint. Handles optional fields, role assignments, and error responses.

  def update_user(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: UpdateUserParams,
  ) -> UserResponse:
      """
      Update an existing user in ServiceNow.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for updating the user.
  
      Returns:
          Response with the updated user details.
      """
      api_url = f"{config.api_url}/table/sys_user/{params.user_id}"
  
      # Build request data
      data = {}
      if params.user_name:
          data["user_name"] = params.user_name
      if params.first_name:
          data["first_name"] = params.first_name
      if params.last_name:
          data["last_name"] = params.last_name
      if params.email:
          data["email"] = params.email
      if params.title:
          data["title"] = params.title
      if params.department:
          data["department"] = params.department
      if params.manager:
          data["manager"] = params.manager
      if params.phone:
          data["phone"] = params.phone
      if params.mobile_phone:
          data["mobile_phone"] = params.mobile_phone
      if params.location:
          data["location"] = params.location
      if params.password:
          data["user_password"] = params.password
      if params.active is not None:
          data["active"] = str(params.active).lower()
  
      # Make request
      try:
          response = requests.patch(
              api_url,
              json=data,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          result = response.json().get("result", {})
  
          # Handle role assignments if provided
          if params.roles:
              assign_roles_to_user(config, auth_manager, params.user_id, params.roles)
  
          return UserResponse(
              success=True,
              message="User updated successfully",
              user_id=result.get("sys_id"),
              user_name=result.get("user_name"),
          )
  
      except requests.RequestException as e:
          logger.error(f"Failed to update user: {e}")
          return UserResponse(
              success=False,
              message=f"Failed to update user: {str(e)}",
          )

• src/servicenow_mcp/tools/user_tools.py:37-53 (schema)

  Pydantic BaseModel defining the input schema for the update_user tool, including all optional fields for user updates.

  class UpdateUserParams(BaseModel):
      """Parameters for updating a user."""
  
      user_id: str = Field(..., description="User ID or sys_id to update")
      user_name: Optional[str] = Field(None, description="Username for the user")
      first_name: Optional[str] = Field(None, description="First name of the user")
      last_name: Optional[str] = Field(None, description="Last name of the user")
      email: Optional[str] = Field(None, description="Email address of the user")
      title: Optional[str] = Field(None, description="Job title of the user")
      department: Optional[str] = Field(None, description="Department the user belongs to")
      manager: Optional[str] = Field(None, description="Manager of the user (sys_id or username)")
      roles: Optional[List[str]] = Field(None, description="Roles to assign to the user")
      phone: Optional[str] = Field(None, description="Phone number of the user")
      mobile_phone: Optional[str] = Field(None, description="Mobile phone number of the user")
      location: Optional[str] = Field(None, description="Location of the user")
      password: Optional[str] = Field(None, description="Password for the user account")
      active: Optional[bool] = Field(None, description="Whether the user account is active")

• src/servicenow_mcp/utils/tool_utils.py:734-740 (registration)

  Tool registration in get_tool_definitions() dictionary, associating the aliased handler function, input schema, return type hint, description, and serialization method.

  "update_user": (
      update_user_tool,
      UpdateUserParams,
      Dict[str, Any],  # Expects dict
      "Update an existing user in ServiceNow",
      "raw_dict",
  ),

• src/servicenow_mcp/tools/__init__.py:67-77 (registration)

  Import statement in tools/__init__.py that exposes the update_user function for use across the module.

  from servicenow_mcp.tools.user_tools import (
      create_user,
      update_user,
      get_user,
      list_users,
      create_group,
      update_group,
      add_group_members,
      remove_group_members,
      list_groups,
  )