Fitbit MCP Server

Instructions

Implementation Reference

• src/heart-rate.ts:155-201 (handler)

  Handler function that constructs the Fitbit API endpoint for heart rate data by date range, fetches the data using makeFitbitRequest, handles errors and empty responses, and returns the raw JSON as text content.

  async ({
    startDate,
    endDate,
  }: HeartRateRangeParams): Promise<ToolResponseStructure> => {
    // Construct the endpoint dynamically
    const endpoint = `activities/heart/date/${startDate}/${endDate}.json`;
  
    // Make the request
    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 the date range '${startDate}' to '${endDate}'. Check token, permissions, date format, and ensure the range is 1 year or less.`,
          },
        ],
        isError: true,
      };
    }
  
    // Handle no data found
    const heartRateEntries = heartRateData['activities-heart'] || [];
    if (heartRateEntries.length === 0) {
      return {
        content: [
          {
            type: 'text',
            text: `No heart rate data found for the date range '${startDate}' to '${endDate}'.`,
          },
        ],
      };
    }
  
    // Return successful response
    const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
    return {
      content: [{ type: 'text', text: rawJsonResponse }],
    };
  }

• src/heart-rate.ts:127-144 (schema)

  Schema definition including tool name, description, Zod input schema for startDate and endDate with regex validation, and TypeScript type for parameters.

  const rangeToolName = 'get_heart_rate_by_date_range';
  const rangeDescription =
    "Get the raw JSON response for heart rate data from Fitbit for a specific date range. Requires 'startDate' and 'endDate' parameters in 'YYYY-MM-DD' format. Note: The API enforces a maximum range of 1 year.";
  
  const rangeParametersSchemaShape = {
    startDate: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Start date must be in YYYY-MM-DD format.')
      .describe(
        'The start date for which to retrieve heart rate data (YYYY-MM-DD).'
      ),
    endDate: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/, 'End date must be in YYYY-MM-DD format.')
      .describe(
        'The end date for which to retrieve heart rate data (YYYY-MM-DD).'
      ),
  };

• src/heart-rate.ts:151-202 (registration)

  Registration of the 'get_heart_rate_by_date_range' tool on the MCP server using server.tool, linking name, description, schema, and handler function.

  server.tool(
    rangeToolName,
    rangeDescription,
    rangeParametersSchemaShape,
    async ({
      startDate,
      endDate,
    }: HeartRateRangeParams): Promise<ToolResponseStructure> => {
      // Construct the endpoint dynamically
      const endpoint = `activities/heart/date/${startDate}/${endDate}.json`;
  
      // Make the request
      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 the date range '${startDate}' to '${endDate}'. Check token, permissions, date format, and ensure the range is 1 year or less.`,
            },
          ],
          isError: true,
        };
      }
  
      // Handle no data found
      const heartRateEntries = heartRateData['activities-heart'] || [];
      if (heartRateEntries.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No heart rate data found for the date range '${startDate}' to '${endDate}'.`,
            },
          ],
        };
      }
  
      // Return successful response
      const rawJsonResponse = JSON.stringify(heartRateData, null, 2);
      return {
        content: [{ type: 'text', text: rawJsonResponse }],
      };
    }
  );