Fathom-Simple-MCP

Instructions

Implementation Reference

• tools/meetings.py:45-113 (handler)

  Core handler function that executes the tool logic: builds API parameters using helper, calls Fathom API to list meetings with filters, handles pagination and errors.
  async def list_meetings( ctx: Context, calendar_invitees: Optional[List[str]] = None, calendar_invitees_domains: Optional[List[str]] = None, created_after: Optional[str] = None, created_before: Optional[str] = None, cursor: Optional[str] = None, include_action_items: Optional[bool] = None, include_crm_matches: Optional[bool] = None, recorded_by: Optional[List[str]] = None, teams: Optional[List[str]] = None, per_page: Optional[int] = None ) -> dict: """Retrieve paginated list of meetings with optional filtering and content inclusion. Returns meeting records with metadata, optionally including action items and CRM matches. Use recording_id from results to fetch individual recording content including summaries. Args: ctx: MCP context for logging calendar_invitees: List of email addresses to filter meetings by attendees calendar_invitees_domains: List of domains to filter meetings by attendee domains created_after: ISO 8601 timestamp (e.g., "2024-01-01T00:00:00Z") - meetings created after this time created_before: ISO 8601 timestamp (e.g., "2024-12-31T23:59:59Z") - meetings created before this time cursor: Pagination cursor from previous response for next page include_action_items: Set True to include action items in response include_crm_matches: Set True to include CRM match data in response recorded_by: List of email addresses to filter by meeting recorder teams: List of team names to filter meetings by associated teams per_page: Number of results per page (default: 50, configurable via DEFAULT_PER_PAGE env var) Returns: dict: { "items": [Meeting objects with fields like title, url, created_at, recording_id, etc.], "limit": int (default 20), "cursor": str (for pagination, null if no more results) } """ try: await ctx.info("Fetching meetings from Fathom API") # Use config default if per_page not provided effective_per_page = per_page if per_page is not None else config.default_per_page # Build parameters params = _build_meetings_params( calendar_invitees=calendar_invitees, calendar_invitees_domains=calendar_invitees_domains, created_after=created_after, created_before=created_before, cursor=cursor, include_action_items=include_action_items, include_crm_matches=include_crm_matches, recorded_by=recorded_by, teams=teams, per_page=effective_per_page ) result = await client.get_meetings(params=params if params else None) await ctx.info("Successfully retrieved meetings") return result except FathomAPIError as e: await ctx.error(f"Fathom API error: {e.message}") raise e except Exception as e: await ctx.error(f"Unexpected error fetching meetings: {str(e)}") raise e
• server.py:106-152 (registration)

  MCP tool registration using @mcp.tool decorator. Defines input schema with Pydantic Field descriptions and defaults. Thin wrapper that delegates to the core implementation in tools/meetings.py.
  @mcp.tool async def list_meetings( ctx: Context, calendar_invitees: list[str] = Field( default=None, description="Filter by invitee emails" ), calendar_invitees_domains: list[str] = Field( default=None, description="Filter by domains" ), created_after: str = Field(default=None, description="ISO timestamp filter"), created_before: str = Field(default=None, description="ISO timestamp filter"), cursor: str = Field(default=None, description="Pagination cursor"), include_action_items: bool = Field( default=None, description="Include action items" ), include_crm_matches: bool = Field(default=None, description="Include CRM matches"), per_page: int = Field( default=config.default_per_page, description=f"Number of results per page (default: {config.default_per_page})", ), recorded_by: list[str] = Field( default=None, description="Filter by recorder emails" ), teams: list[str] = Field(default=None, description="Filter by team names"), ) -> Dict[str, Any]: """Retrieve paginated meetings with filtering and optional content inclusion (action items, CRM matches). Examples: list_meetings() # Get all meetings (paginated) list_meetings(created_after="2024-01-01T00:00:00Z") # Meetings after specific date list_meetings(teams=["Sales", "Engineering"]) # Filter by specific teams list_meetings(calendar_invitees=["john.doe@company.com", "jane.smith@client.com"]) # Filter by specific attendees list_meetings(calendar_invitees_domains=["company.com", "client.com"]) # Filter by attendee domains """ return await tools.meetings.list_meetings( ctx, calendar_invitees=calendar_invitees, calendar_invitees_domains=calendar_invitees_domains, created_after=created_after, created_before=created_before, cursor=cursor, include_action_items=include_action_items, include_crm_matches=include_crm_matches, per_page=per_page, recorded_by=recorded_by, teams=teams )
• tools/meetings.py:7-43 (helper)

  Supporting utility function that constructs the query parameters dictionary for the Fathom API call based on provided filters.
  def _build_meetings_params( calendar_invitees: Optional[List[str]] = None, calendar_invitees_domains: Optional[List[str]] = None, created_after: Optional[str] = None, created_before: Optional[str] = None, cursor: Optional[str] = None, include_action_items: Optional[bool] = None, include_crm_matches: Optional[bool] = None, recorded_by: Optional[List[str]] = None, teams: Optional[List[str]] = None, per_page: Optional[int] = None ) -> dict: """Build API parameters dict from function arguments""" params = {} if calendar_invitees: params["calendar_invitees[]"] = calendar_invitees if calendar_invitees_domains: params["calendar_invitees_domains[]"] = calendar_invitees_domains if created_after: params["created_after"] = created_after if created_before: params["created_before"] = created_before if cursor: params["cursor"] = cursor if include_action_items is not None: params["include_action_items"] = include_action_items if include_crm_matches is not None: params["include_crm_matches"] = include_crm_matches if recorded_by: params["recorded_by[]"] = recorded_by if teams: params["teams[]"] = teams if per_page is not None: params["limit"] = per_page return params
• tools/meetings.py:58-82 (schema)

  Detailed docstring defining input parameters, their descriptions, and output schema for the list_meetings tool.
  """Retrieve paginated list of meetings with optional filtering and content inclusion. Returns meeting records with metadata, optionally including action items and CRM matches. Use recording_id from results to fetch individual recording content including summaries. Args: ctx: MCP context for logging calendar_invitees: List of email addresses to filter meetings by attendees calendar_invitees_domains: List of domains to filter meetings by attendee domains created_after: ISO 8601 timestamp (e.g., "2024-01-01T00:00:00Z") - meetings created after this time created_before: ISO 8601 timestamp (e.g., "2024-12-31T23:59:59Z") - meetings created before this time cursor: Pagination cursor from previous response for next page include_action_items: Set True to include action items in response include_crm_matches: Set True to include CRM match data in response recorded_by: List of email addresses to filter by meeting recorder teams: List of team names to filter meetings by associated teams per_page: Number of results per page (default: 50, configurable via DEFAULT_PER_PAGE env var) Returns: dict: { "items": [Meeting objects with fields like title, url, created_at, recording_id, etc.], "limit": int (default 20), "cursor": str (for pagination, null if no more results) } """