Fathom AI MCP

Instructions

Implementation Reference

• src/fathom-client.ts:88-119 (handler)

  The listMeetings method in FathomClient performs the actual API request to fetch meetings.

  async listMeetings(
    options: {
      cursor?: string | null;
      created_after?: string | null;
      created_before?: string | null;
      meeting_type?: string | null;
      calendar_invitees_domains?: string[] | null;
      calendar_invitees_domains_type?: string | null;
      recorded_by?: string[] | null;
      teams?: string[] | null;
    } = {}
  ): Promise<Record<string, unknown>> {
    const params: Record<string, unknown> = {
      cursor: options.cursor,
      created_after: options.created_after,
      created_before: options.created_before,
      meeting_type: options.meeting_type,
      calendar_invitees_domains_type: options.calendar_invitees_domains_type,
    };
    if (options.calendar_invitees_domains) {
      params['calendar_invitees_domains[]'] = options.calendar_invitees_domains;
    }
    if (options.recorded_by) {
      params['recorded_by[]'] = options.recorded_by;
    }
    if (options.teams) {
      params['teams[]'] = options.teams;
    }
    return this._get('/meetings', params);
  }
  
  async getTranscript(recordingId: number): Promise<Record<string, unknown>> {

• src/server.ts:250-345 (registration)

  The 'list_meetings' tool is registered in src/server.ts, including its schema and handler function.

  server.registerTool(
    'list_meetings',
    {
      description:
        'List meetings with optional filtering and pagination. All timestamps are UTC. Use get_summary or get_transcript for detailed content.',
      inputSchema: {
        page: z
          .number()
          .int()
          .min(1)
          .default(1)
          .describe('Page number (starts at 1). Any page can be requested directly.'),
        page_size: z
          .number()
          .int()
          .min(1)
          .default(DEFAULT_PAGE_SIZE)
          .describe('Number of meetings per page (default 10).'),
        participants: z
          .array(z.string())
          .optional()
          .describe(
            'Filter by participant email addresses (calendar invitees and recorder). Use with participants_match to control matching logic.'
          ),
        participants_match: z
          .enum(['any', 'all'])
          .default('any')
          .describe(
            "How to match participants: 'any' returns meetings with at least one match, 'all' returns only meetings where every listed participant is present."
          ),
        created_after: z
          .string()
          .optional()
          .describe('ISO timestamp to filter meetings created after this date.'),
        created_before: z
          .string()
          .optional()
          .describe('ISO timestamp to filter meetings created before this date.'),
        meeting_type: z
          .enum(['internal', 'external'])
          .optional()
          .describe("Filter by 'internal' or 'external'."),
        calendar_invitees_domains: z
          .array(z.string())
          .optional()
          .describe('Filter by invitee email domains (e.g. ["acme.com"]).'),
        calendar_invitees_domains_type: z
          .enum(['all', 'only_internal', 'one_or_more_external'])
          .optional()
          .describe("Filter invitee type: 'all', 'only_internal', or 'one_or_more_external'."),
        recorded_by: z.array(z.string()).optional().describe('Filter by recorder email addresses.'),
        teams: z.array(z.string()).optional().describe('Filter by team names.'),
      },
    },
    async args => {
      const client = getClient();
      const apiKwargs: Record<string, unknown> = {
        created_after: args.created_after,
        created_before: args.created_before,
        meeting_type: args.meeting_type,
        calendar_invitees_domains: args.calendar_invitees_domains,
        calendar_invitees_domains_type: args.calendar_invitees_domains_type,
        recorded_by: args.recorded_by,
        teams: args.teams,
      };
      const key = cacheKey('list_meetings', {
        ...apiKwargs,
        participants: args.participants,
        participants_match: args.participants_match,
      });
  
      let cached = _itemsCache.get(key);
      const isExpired = cached !== undefined && Date.now() - cached.fetchedAt > CACHE_TTL_MS;
      if (!cached || isExpired) {
        try {
          const result = await fetchAll(
            opts => client.listMeetings(opts as Record<string, unknown>),
            apiKwargs
          );
          let { items } = result;
          if (args.participants && args.participants.length > 0) {
            items = filterByParticipants(
              items,
              args.participants,
              args.participants_match === 'all'
            );
          }
          const entry = { items, truncated: result.truncated, fetchedAt: Date.now() };
          _itemsCache.set(key, entry);
          cached = entry;
        } catch (err) {
          const msg = err instanceof Error ? err.message : String(err);
          return { content: [{ type: 'text', text: `Error fetching meetings: ${msg}` }] };
        }
      }