get_upcoming_events
Retrieve scheduled music events for a specific city within a defined date range, optionally filtered by keywords, using Ticketmaster API integration. Ideal for dynamic event planning and real-time data access.
Instructions
Get upcoming music events for a city.
Args: city: City in which to search for events. start_dttm_str: Start date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-08T00:00:00Z end_dttm_str: Start date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-10T00:00:00Z keyword: Any optional keywords to help filter search results.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | ||
| end_dttm_str | Yes | ||
| keyword | No | ||
| start_dttm_str | Yes |
Implementation Reference
- src/mcp_live_events/server.py:8-23 (handler)The main handler function for the 'get_upcoming_events' tool, decorated with @mcp.tool(). It fetches events using EventsApiClient and formats them with format_events.@mcp.tool() async def get_upcoming_events(city: str, start_dttm_str: str, end_dttm_str: str, keyword: str | None = None) -> str: """ Get upcoming music events for a city. Args: city: City in which to search for events. start_dttm_str: Start date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-08T00:00:00Z end_dttm_str: Start date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-10T00:00:00Z keyword: Any optional keywords to help filter search results. """ data = await EventsApiClient().fetch_events(city=city, start_dttm_str=start_dttm_str, end_dttm_str=end_dttm_str, keyword=keyword) return format_events(data)
- The EventsApiClient.fetch_events method called by the handler to query the Ticketmaster API for upcoming events.async def fetch_events( self, city: str, start_dttm_str: str, end_dttm_str: str, classification_name: str = "Music", keyword: str | None = None, ) -> dict | None: async with httpx.AsyncClient() as client: try: params = { "apikey": self.api_key, "city": city, "startDateTime": start_dttm_str, "endDateTime": end_dttm_str, "classificationName": classification_name, "size": 100, } if keyword: params["keyword"] = keyword response = await client.get( f"{self.base_url}/events.json", params=params, timeout=30.0, ) response.raise_for_status() return response.json() except Exception: return None
- src/mcp_live_events/utils.py:1-17 (helper)The format_events utility function used by the handler to format the API response into a readable string.def format_events(response_dict: dict) -> str: if not response_dict: return "No events found!" return "\n\n".join( [ f""" Name: {event.get("name")} Link: {event.get("url")} Event Datetime: {event.get("dates")["start"]["dateTime"]} Genres: {", ".join(set(c["genre"]["name"] for c in event.get("classifications")))} Info: {event.get("info")} Venue: {event.get("_embedded")["venues"][0]["name"]} """ for event in response_dict["_embedded"]["events"] ] )
- src/mcp_live_events/schemas.py:5-27 (schema)Pydantic schema definition for upcoming events request, matching the tool parameters (note: tool name differs).class UpcomingEventsRequest(BaseModel): """ Schema for the UpcomingEventsRequest tool, which searches Ticketmaster for upcoming music events. """ city: str = Field(description="City in which search for events.") start_dttm_str: str = Field( description="Start date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-08T00:00:00Z" ) end_dttm_str: str = Field( description="End date/time in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Example: 2025-02-28T23:59:59Z" ) keyword: str | None = Field( None, description="Any optional keywords to help filter search results." ) @classmethod def as_tool(cls) -> Tool: return Tool( name="UpcomingEventsRequest", description="Fetch upcoming events based on city, time range, and keyword.", inputSchema=cls.model_json_schema(), )
- src/mcp_live_events/server.py:6-6 (registration)Initialization of the FastMCP server instance where tools are registered via decorators.mcp = FastMCP("mcp-live-events")