Fathom MCP Server

Implementation Reference

• src/index.ts:54-83 (handler)

  Primary handler implementation for the 'list_meetings' MCP tool. Registers the tool with input schema (Zod), destructures params, calls FathomClient.listMeetings with mapped filters, applies client-side limit slicing, formats output using formatMeetingList, and returns markdown text content.

  server.tool(
    'list_meetings',
    {
      limit: z.number().optional().describe('Maximum number of meetings to return (default: 10, use 0 for all)'),
      created_after: z.string().optional().describe('ISO 8601 timestamp - only return meetings after this date'),
      created_before: z.string().optional().describe('ISO 8601 timestamp - only return meetings before this date'),
      include_external_only: z.boolean().optional().describe('Only include meetings with external participants'),
    },
    async ({ limit, created_after, created_before, include_external_only }) => {
      console.error('Fetching meetings...');
      
      const response = await fathom.listMeetings({
        created_after,
        created_before,
        calendar_invitees_domains_type: include_external_only ? 'one_or_more_external' : undefined,
      });
  
      let meetings = response.items;
      if (limit && limit > 0) {
        meetings = meetings.slice(0, limit);
      }
  
      console.error(`Found ${meetings.length} meetings`);
      const markdown = formatMeetingList(meetings);
      
      return {
        content: [{ type: 'text', text: markdown }],
      };
    }
  );

• src/fathom-client.ts:145-158 (schema)

  TypeScript interface defining all possible parameters for listing meetings via Fathom API. Used by the tool handler to construct API request params (maps tool params to subset: created_after/before, calendar_invitees_domains_type).

  export interface ListMeetingsParams {
    include_transcript?: boolean;
    include_summary?: boolean;
    include_action_items?: boolean;
    include_crm_matches?: boolean;
    created_after?: string;
    created_before?: string;
    recorded_by?: string[];
    teams?: string[];
    calendar_invitees?: string[];
    calendar_invitees_domains?: string[];
    calendar_invitees_domains_type?: 'all' | 'only_internal' | 'one_or_more_external';
    cursor?: string;
  }

• src/fathom-client.ts:207-231 (helper)

  FathomClient helper method invoked by the tool handler. Builds query string from ListMeetingsParams and makes authenticated GET request to Fathom API /meetings endpoint.

  async listMeetings(params: ListMeetingsParams = {}): Promise<MeetingsResponse> {
    const searchParams = new URLSearchParams();
    
    if (params.include_transcript) searchParams.append('include_transcript', 'true');
    if (params.include_summary) searchParams.append('include_summary', 'true');
    if (params.include_action_items) searchParams.append('include_action_items', 'true');
    if (params.include_crm_matches) searchParams.append('include_crm_matches', 'true');
    if (params.created_after) searchParams.append('created_after', params.created_after);
    if (params.created_before) searchParams.append('created_before', params.created_before);
    if (params.cursor) searchParams.append('cursor', params.cursor);
    if (params.calendar_invitees_domains_type) {
      searchParams.append('calendar_invitees_domains_type', params.calendar_invitees_domains_type);
    }
    
    // Handle array params
    params.recorded_by?.forEach(email => searchParams.append('recorded_by[]', email));
    params.teams?.forEach(team => searchParams.append('teams[]', team));
    params.calendar_invitees?.forEach(email => searchParams.append('calendar_invitees[]', email));
    params.calendar_invitees_domains?.forEach(domain => searchParams.append('calendar_invitees_domains[]', domain));
  
    const queryString = searchParams.toString();
    const endpoint = `/meetings${queryString ? `?${queryString}` : ''}`;
    
    return this.request<MeetingsResponse>(endpoint);
  }

• src/formatters.ts:239-259 (helper)

  Utility function called by the tool handler to format the fetched meetings array into a markdown table with columns for title, date, duration, recorder, participant count, and ID.

  export function formatMeetingList(meetings: Meeting[]): string {
    if (meetings.length === 0) {
      return 'No meetings found.';
    }
  
    const rows = meetings.map(m => {
      const title = m.title || m.meeting_title || `Meeting ${m.recording_id}`;
      const date = formatDate(m.recording_start_time);
      const duration = formatDuration(m.recording_start_time, m.recording_end_time);
      const recorder = m.recorded_by.name;
      const participants = m.calendar_invitees.length;
      
      return `| ${title} | ${date} | ${duration} | ${recorder} | ${participants} | ${m.recording_id} |`;
    });
  
    return [
      '| Title | Date | Duration | Recorded By | Participants | ID |',
      '|-------|------|----------|-------------|--------------|-----|',
      ...rows,
    ].join('\n');
  }