Fitbit MCP Server

Instructions

Implementation Reference

• src/azm-timeseries.ts:43-54 (handler)

  Handler function that constructs the specific API endpoint for Active Zone Minutes (AZM) time series and invokes the shared handleFitbitApiCall utility to fetch data from Fitbit.

  handler: async ({ startDate, endDate }: AzmTimeSeriesParams) => {
    const endpoint = `activities/active-zone-minutes/date/${startDate}/${endDate}.json`;
    
    return handleFitbitApiCall<AzmTimeSeriesResponse, AzmTimeSeriesParams>(
      endpoint,
      { startDate, endDate },
      getAccessTokenFn,
      {
        errorContext: `AZM data from ${startDate} to ${endDate}`
      }
    );
  }

• src/azm-timeseries.ts:34-42 (schema)

  Parameter type definition (AzmTimeSeriesParams) and input schema using shared CommonSchemas for startDate and endDate validation.

  type AzmTimeSeriesParams = Pick<CommonParams, 'startDate' | 'endDate'>;
  
  registerTool(server, {
    name: 'get_azm_timeseries',
    description: "Get the raw JSON response for Active Zone Minutes (AZM) time series data from Fitbit over a date range (max 1095 days). Returns total AZM plus breakdown by fat burn, cardio, and peak zones.",
    parametersSchema: {
      startDate: CommonSchemas.startDate,
      endDate: CommonSchemas.endDate,
    },

• src/azm-timeseries.ts:30-56 (registration)

  Module-level registration function that configures and registers the get_azm_timeseries tool with the MCP server.

  export function registerAzmTimeSeriesTool(
    server: McpServer,
    getAccessTokenFn: () => Promise<string | null>
  ): void {
    type AzmTimeSeriesParams = Pick<CommonParams, 'startDate' | 'endDate'>;
  
    registerTool(server, {
      name: 'get_azm_timeseries',
      description: "Get the raw JSON response for Active Zone Minutes (AZM) time series data from Fitbit over a date range (max 1095 days). Returns total AZM plus breakdown by fat burn, cardio, and peak zones.",
      parametersSchema: {
        startDate: CommonSchemas.startDate,
        endDate: CommonSchemas.endDate,
      },
      handler: async ({ startDate, endDate }: AzmTimeSeriesParams) => {
        const endpoint = `activities/active-zone-minutes/date/${startDate}/${endDate}.json`;
        
        return handleFitbitApiCall<AzmTimeSeriesResponse, AzmTimeSeriesParams>(
          endpoint,
          { startDate, endDate },
          getAccessTokenFn,
          {
            errorContext: `AZM data from ${startDate} to ${endDate}`
          }
        );
      }
    });
  }

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

  Invocation of the tool registration during MCP server setup in the main entry point.

  registerAzmTimeSeriesTool(server, getAccessToken);

• src/utils.ts:183-222 (helper)

  Core helper function used by the tool handler to perform the Fitbit API request, handle errors, and format the MCP tool response.

  export async function handleFitbitApiCall<TResponse, TParams>(
    endpoint: string,
    params: TParams,
    getAccessTokenFn: () => Promise<string | null>,
    options: {
      apiBase?: string;
      successDataExtractor?: (data: TResponse) => unknown[] | null;
      noDataMessage?: string;
      errorContext?: string;
    } = {}
  ): Promise<ToolResponseStructure> {
    const {
      apiBase = FITBIT_API_VERSIONS.V1,
      successDataExtractor,
      noDataMessage,
      errorContext = JSON.stringify(params)
    } = options;
  
    const responseData = await makeFitbitRequest<TResponse>(
      endpoint,
      getAccessTokenFn,
      apiBase
    );
  
    if (!responseData) {
      return createErrorResponse(
        `${ERROR_MESSAGES.API_REQUEST_FAILED} for ${errorContext}. ${ERROR_MESSAGES.CHECK_TOKEN_PERMISSIONS}.`
      );
    }
  
    // Check for empty data if extractor provided
    if (successDataExtractor) {
      const extractedData = successDataExtractor(responseData);
      if (!extractedData || extractedData.length === 0) {
        return createNoDataResponse(noDataMessage || errorContext);
      }
    }
  
    return createSuccessResponse(responseData);
  }