Fitbit MCP Server

Instructions

Implementation Reference

• src/weight.ts:39-52 (handler)

  The handler function that executes the get_weight tool logic: constructs the Fitbit API endpoint for body weight data over a given period and invokes handleFitbitApiCall to fetch, extract, and format the response.

  handler: async ({ period }: WeightParams) => {
    const endpoint = `/body/weight/date/today/${period}.json`;
    
    return handleFitbitApiCall<WeightTimeSeriesResponse, WeightParams>(
      endpoint,
      { period },
      getAccessTokenFn,
      {
        successDataExtractor: (data) => data['body-weight'] || [],
        noDataMessage: `the period '${period}'`,
        errorContext: `period '${period}'`
      }
    );
  }

• src/weight.ts:33-53 (registration)

  Registration of the get_weight tool via registerTool, specifying name, description, input schema (period parameter), and handler function.

  registerTool(server, {
    name: 'get_weight',
    description: "Get the raw JSON response for weight entries from Fitbit for a specified period ending today. Requires a 'period' parameter such as '1d', '7d', '30d', '3m', '6m', '1y'",
    parametersSchema: {
      period: CommonSchemas.period,
    },
    handler: async ({ period }: WeightParams) => {
      const endpoint = `/body/weight/date/today/${period}.json`;
      
      return handleFitbitApiCall<WeightTimeSeriesResponse, WeightParams>(
        endpoint,
        { period },
        getAccessTokenFn,
        {
          successDataExtractor: (data) => data['body-weight'] || [],
          noDataMessage: `the period '${period}'`,
          errorContext: `period '${period}'`
        }
      );
    }
  });

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

  Top-level call to registerWeightTool, which sets up the get_weight tool on the MCP server instance.

  registerWeightTool(server, getAccessToken);

• src/weight.ts:10-19 (schema)

  TypeScript interfaces defining the structure of Fitbit weight time series data used in the tool's handler.

  interface WeightTimeSeriesEntry {
    dateTime: string; // Date (and potentially time) of the entry
    value: string; // Weight value as a string
  }
  
  // Represents the structure of the response from the Fitbit Time Series API for weight
  interface WeightTimeSeriesResponse {
    'body-weight': WeightTimeSeriesEntry[]; // Array of weight entries
  }

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

  Shared helper function handleFitbitApiCall used by the get_weight handler to perform the API request, handle authentication, errors, no-data cases, 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);
  }