cloudtrail_lookup_events
Search AWS CloudTrail management events using specific filters to audit API activity and monitor account changes.
Instructions
Lookup CloudTrail events using filters.
If the user request falls into one of these scenarios, use the Athena tools instead:
- EventName is a data event (e.g. GetObject, DeleteObject, PutObject);
- the user wants to filter by role name;
- the user wants to filter by principal ID;
- the user wants to filter by IP address;
- the user wants to filter by bucket name;
- the user wants to filter by file object in buckets;
- the user wants to filter using regex;
When filtering for EventName, note that the event name is case-sensitive and must match the exact name of the event.
If you want to use operators like 'equals', 'not equals', 'contains', etc., you must use the Athena tools instead.
<IMPORTANT>
Call datetime.datetime.now() to get the current date and time before providing the start and end times.
If the user asks for events happened in the last 7 days, run 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date.
Print out the start and end times to the user.
</IMPORTANT>
Parameters:
aws_region (str): The AWS region - use 'us-east-1' if not specified.
attribute_key (str): The name of the event to search for.
Valid attributes keys: EventId | EventName | ReadOnly | Username | ResourceType | ResourceName | EventSource | AccessKeyId
attribute_value (str): The value of the event to search for.
If no key-value pair is provided, use 'ReadOnly'='false'.
start_time (str): start timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-10 12:45:50').
If not provided, use 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date.
end_time (str): end timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-11 12:45:50').
If not provided, use 'datetime.datetime.now()' to get the end date.
max_results (int): Maximum number of events to return.
Returns:
list: A list of CloudTrail events matching the specified criteria.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aws_region | Yes | ||
| attribute_key | Yes | ||
| attribute_value | Yes | ||
| start_time | Yes | ||
| end_time | Yes | ||
| max_results | No |
Implementation Reference
- server.py:31-94 (handler)The handler function for 'cloudtrail_lookup_events' tool. It is registered via @mcp.tool() decorator and implements the AWS CloudTrail 'lookup_events' API call, filtering by attribute key-value pair, time range, and max results. Returns a list of event summaries or error message.
@mcp.tool() async def cloudtrail_lookup_events( aws_region: str, attribute_key: str, attribute_value: str, start_time: str, end_time: str, max_results: int = 50 ) -> list: """ Lookup CloudTrail events using filters. If the user request falls into one of these scenarios, use the Athena tools instead: - EventName is a data event (e.g. GetObject, DeleteObject, PutObject); - the user wants to filter by role name; - the user wants to filter by principal ID; - the user wants to filter by IP address; - the user wants to filter by bucket name; - the user wants to filter by file object in buckets; - the user wants to filter using regex; When filtering for EventName, note that the event name is case-sensitive and must match the exact name of the event. If you want to use operators like 'equals', 'not equals', 'contains', etc., you must use the Athena tools instead. <IMPORTANT> Call datetime.datetime.now() to get the current date and time before providing the start and end times. If the user asks for events happened in the last 7 days, run 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date. Print out the start and end times to the user. </IMPORTANT> Parameters: aws_region (str): The AWS region - use 'us-east-1' if not specified. attribute_key (str): The name of the event to search for. Valid attributes keys: EventId | EventName | ReadOnly | Username | ResourceType | ResourceName | EventSource | AccessKeyId attribute_value (str): The value of the event to search for. If no key-value pair is provided, use 'ReadOnly'='false'. start_time (str): start timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-10 12:45:50'). If not provided, use 'datetime.datetime.now() - datetime.timedelta(days=7)' to get the start date. end_time (str): end timestamp with format 'YYYY-MM-DD HH:MM:SS' (e.g. '2025-04-11 12:45:50'). If not provided, use 'datetime.datetime.now()' to get the end date. max_results (int): Maximum number of events to return. Returns: list: A list of CloudTrail events matching the specified criteria. """ try: cloudtrail_client = boto3.client('cloudtrail', region_name=aws_region) response = cloudtrail_client.lookup_events( LookupAttributes=[{'AttributeKey': attribute_key, 'AttributeValue': attribute_value}], StartTime=start_time, EndTime=end_time, MaxResults=max_results ) events = response.get('Events', []) return [ { 'EventId': event.get('EventId'), 'EventName': event.get('EventName'), 'EventTime': event.get('EventTime').isoformat() if event.get('EventTime') else None, 'Username': event.get('Username') } for event in events ] except Exception as e: return f"Error looking up events: {str(e)}"