MCP Fathom Analytics

Instructions

Implementation Reference

• src/tools/visitors.ts:13-67 (handler)

  The asynchronous handler function that executes the tool logic: fetches current visitors from Fathom API based on site_id and optional detailed flag, formats the response as markdown text blocks, handles no visitors and errors.

  async ({ site_id, detailed = false }) => {
      try {
          const visitorsData = await fathomClient.api.reports.currentVisitors({
              site_id,
              detailed
          });
          
          if (visitorsData.total === 0) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `No current visitors for site ${site_id}.`,
                      },
                  ],
              };
          }
  
          let responseText = `Current visitors for site ${site_id}: ${visitorsData.total}\n\n`;
          
          // Include detailed information if available and requested
          if (detailed && visitorsData.content && visitorsData.content.length > 0) {
              responseText += "Top Content:\n";
              visitorsData.content.forEach((item, index) => {
                  responseText += `${index + 1}. ${item.hostname}${item.pathname} - ${item.total} visitor(s)\n`;
              });
              responseText += "\n";
          }
          
          if (detailed && visitorsData.referrers && visitorsData.referrers.length > 0) {
              responseText += "Top Referrers:\n";
              visitorsData.referrers.forEach((item, index) => {
                  responseText += `${index + 1}. ${item.referrer_hostname}${item.referrer_pathname} - ${item.total} visitor(s)\n`;
              });
          }
          
          return {
              content: [
                  {
                      type: "text",
                      text: responseText,
                  },
              ],
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to retrieve current visitors: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`,
                  },
              ],
          };
      }
  },

• src/tools/visitors.ts:10-12 (schema)

  Zod input schema defining parameters: required site_id (string) and optional detailed (boolean).

      site_id: z.string().describe("ID of the site to retrieve current visitors for"),
      detailed: z.boolean().optional().describe("Whether to include detailed content and referrer information"),
  },

• src/tools/visitors.ts:6-68 (registration)

  MCP server.tool() registration of the 'get-current-visitors' tool, including name, description, input schema, and handler function.

  server.tool(
      "get-current-visitors",
      "Get current visitors for a Fathom Analytics site",
      {
          site_id: z.string().describe("ID of the site to retrieve current visitors for"),
          detailed: z.boolean().optional().describe("Whether to include detailed content and referrer information"),
      },
      async ({ site_id, detailed = false }) => {
          try {
              const visitorsData = await fathomClient.api.reports.currentVisitors({
                  site_id,
                  detailed
              });
              
              if (visitorsData.total === 0) {
                  return {
                      content: [
                          {
                              type: "text",
                              text: `No current visitors for site ${site_id}.`,
                          },
                      ],
                  };
              }
  
              let responseText = `Current visitors for site ${site_id}: ${visitorsData.total}\n\n`;
              
              // Include detailed information if available and requested
              if (detailed && visitorsData.content && visitorsData.content.length > 0) {
                  responseText += "Top Content:\n";
                  visitorsData.content.forEach((item, index) => {
                      responseText += `${index + 1}. ${item.hostname}${item.pathname} - ${item.total} visitor(s)\n`;
                  });
                  responseText += "\n";
              }
              
              if (detailed && visitorsData.referrers && visitorsData.referrers.length > 0) {
                  responseText += "Top Referrers:\n";
                  visitorsData.referrers.forEach((item, index) => {
                      responseText += `${index + 1}. ${item.referrer_hostname}${item.referrer_pathname} - ${item.total} visitor(s)\n`;
                  });
              }
              
              return {
                  content: [
                      {
                          type: "text",
                          text: responseText,
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to retrieve current visitors: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`,
                      },
                  ],
              };
          }
      },
  );