cloudtrail_lookup_events
Filter and retrieve specific AWS CloudTrail events using criteria like EventName, ReadOnly, Username, and timestamps. Ideal for auditing and monitoring API activity within a specified AWS region.
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
| Name | Required | Description | Default |
|---|---|---|---|
| attribute_key | Yes | ||
| attribute_value | Yes | ||
| aws_region | Yes | ||
| end_time | Yes | ||
| max_results | No | ||
| start_time | Yes |
Input Schema (JSON Schema)
{
"properties": {
"attribute_key": {
"title": "Attribute Key",
"type": "string"
},
"attribute_value": {
"title": "Attribute Value",
"type": "string"
},
"aws_region": {
"title": "Aws Region",
"type": "string"
},
"end_time": {
"title": "End Time",
"type": "string"
},
"max_results": {
"default": 50,
"title": "Max Results",
"type": "integer"
},
"start_time": {
"title": "Start Time",
"type": "string"
}
},
"required": [
"aws_region",
"attribute_key",
"attribute_value",
"start_time",
"end_time"
],
"title": "cloudtrail_lookup_eventsArguments",
"type": "object"
}
Implementation Reference
- server.py:31-94 (handler)The @mcp.tool() decorator registers the cloudtrail_lookup_events handler function, which implements the core logic for looking up CloudTrail events using the AWS boto3 CloudTrail client. It filters events by attribute key-value pairs, time range, and maximum results, returning a list of event summaries.@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)}"