Fitbit MCP Server

Instructions

Implementation Reference

• src/heart-rate.ts:77-122 (handler)

  The handler function that executes the 'get_heart_rate' tool logic. It makes a request to the Fitbit API for heart rate data over a specified period ending on a given date (default 'today'), handles errors and empty responses, and returns the raw JSON data as text.

  async ({
    period,
    date = 'today',
  }: HeartRatePeriodParams): Promise<ToolResponseStructure> => {
    // Construct the endpoint dynamically
    const endpoint = `activities/heart/date/${date}/${period}.json`;
  
    const heartRateData =
      await makeFitbitRequest<HeartRateTimeSeriesResponse>(
        endpoint,
        getAccessTokenFn,
        FITBIT_API_BASE
      );
  
    // Handle API call failure
    if (!heartRateData) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to retrieve heart rate data from Fitbit API for date '${date}' and period '${period}'. Check token and permissions.`,
          },
        ],
        isError: true,
      };
    }
  
    // Handle no data found for the period
    const heartRateEntries = heartRateData['activities-heart'] || [];
    if (heartRateEntries.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: `No heart rate data found for date '${date}' and period '${period}'.`,
          },
        ],
      };
    }
  
    // Return successful response with raw JSON
    const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
    return {
      content: [{ type: 'text', text: rawJsonResponse }],
    };
  }

• src/heart-rate.ts:52-66 (schema)

  Input schema (Zod) for the 'get_heart_rate' tool parameters: 'period' (required enum) and 'date' (optional string).

  const periodParametersSchemaShape = {
    period: z
      .enum(['1d', '7d', '30d', '1w', '1m'])
      .describe('The time period for which to retrieve heart rate data.'),
    date: z
      .string()
      .regex(
        /^\d{4}-\d{2}-\d{2}$|^today$/,
        "Date must be in YYYY-MM-DD format or 'today'."
      )
      .optional()
      .describe(
        "The date for which to retrieve heart rate data (YYYY-MM-DD or 'today'). Defaults to 'today'."
      ),
  };

• src/heart-rate.ts:73-123 (registration)

  Registration of the 'get_heart_rate' tool on the MCP server using server.tool(name, description, schema, handler). The handler is defined inline.

  server.tool(
    periodToolName,
    periodDescription,
    periodParametersSchemaShape,
    async ({
      period,
      date = 'today',
    }: HeartRatePeriodParams): Promise<ToolResponseStructure> => {
      // Construct the endpoint dynamically
      const endpoint = `activities/heart/date/${date}/${period}.json`;
  
      const heartRateData =
        await makeFitbitRequest<HeartRateTimeSeriesResponse>(
          endpoint,
          getAccessTokenFn,
          FITBIT_API_BASE
        );
  
      // Handle API call failure
      if (!heartRateData) {
        return {
          content: [
            {
              type: 'text',
              text: `Failed to retrieve heart rate data from Fitbit API for date '${date}' and period '${period}'. Check token and permissions.`,
            },
          ],
          isError: true,
        };
      }
  
      // Handle no data found for the period
      const heartRateEntries = heartRateData['activities-heart'] || [];
      if (heartRateEntries.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No heart rate data found for date '${date}' and period '${period}'.`,
            },
          ],
        };
      }
  
      // Return successful response with raw JSON
      const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
      return {
        content: [{ type: 'text', text: rawJsonResponse }],
      };
    }
  );

• src/index.ts:81-81 (registration)

  Call to registerHeartRateTools in the main index.ts, which registers the 'get_heart_rate' tool (and related) on the MCP server instance.

  registerHeartRateTools(server, getAccessToken);