AirNow MCP Server

Instructions

Implementation Reference

• src/tools/historical-observations-by-reporting-area-by-zip-code.ts:32-56 (handler)

  MCP tool handler that invokes the AirNow API and returns the response as text content or an error.

  async (params) => {
    const result =
      await airnowApi.fetchHistoricalObservationsByReportingAreaByZipCode(
        params
      );
    if (result === null) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to fetch historical observations data from AirNow API.",
          },
        ],
        isError: true,
      };
    }
    return {
      content: [
        {
          type: "text",
          text: result,
        },
      ],
    };
  }

• src/tools/historical-observations-by-reporting-area-by-zip-code.ts:10-31 (schema)

  Zod schema defining the input parameters for the tool.

    zipCode: z
      .string()
      .describe(
        "Zip code to get the historical observations for. Example: 94954"
      ),
    date: z
      .string()
      .describe(
        "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01"
      ),
    format: z
      .enum(["text/csv", "application/json", "application/xml"])
      .describe(
        "Format of the payload file returned. Example: application/json"
      ),
    distance: z
      .string()
      .optional()
      .describe(
        "If no reporting area is associated with the Zip code, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
      ),
  },

• src/tools/historical-observations-by-reporting-area-by-zip-code.ts:5-58 (registration)

  Function that registers the tool with the MCP server, including name, description, schema, and handler.

  export const registerHistoricalObservationsByZipCode = (server: McpServer): void => {
    server.tool(
      "get-historical-observations-by-reporting-area-by-zip-code",
      "Get historical AQI values and categories for a reporting area by Zip code.",
      {
        zipCode: z
          .string()
          .describe(
            "Zip code to get the historical observations for. Example: 94954"
          ),
        date: z
          .string()
          .describe(
            "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01"
          ),
        format: z
          .enum(["text/csv", "application/json", "application/xml"])
          .describe(
            "Format of the payload file returned. Example: application/json"
          ),
        distance: z
          .string()
          .optional()
          .describe(
            "If no reporting area is associated with the Zip code, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
          ),
      },
      async (params) => {
        const result =
          await airnowApi.fetchHistoricalObservationsByReportingAreaByZipCode(
            params
          );
        if (result === null) {
          return {
            content: [
              {
                type: "text",
                text: "Failed to fetch historical observations data from AirNow API.",
              },
            ],
            isError: true,
          };
        }
        return {
          content: [
            {
              type: "text",
              text: result,
            },
          ],
        };
      }
    );
  };

• src/airnow-api.ts:63-72 (helper)

  Core helper function that performs the HTTP request to the AirNow API for historical observations by zip code.

  export async function fetchHistoricalObservationsByReportingAreaByZipCode(params: Record<string, string>): Promise<string | null> {
    const endpoint = 'aq/observation/zipcode/historical/';
    const queryParams = new URLSearchParams();
    queryParams.append('zipCode', params.zipCode);
    queryParams.append('date', params.date);
    queryParams.append('format', params.format);
    if (params.distance) queryParams.append('distance', params.distance);
  
    return airnowGet(endpoint, queryParams);
  }

• src/tools/index.ts:10-22 (registration)

  Imports and calls the register function as part of registering all tools.

  import { registerHistoricalObservationsByZipCode } from "./historical-observations-by-reporting-area-by-zip-code.js";
  import { registerObservationsByBoundingBox } from "./observations-by-monitoring-site-by-geographic-bounding-box.js";
  
  export const registerTools = (server: McpServer): void => {
    registerContourMapsByBoundingBoxCombined(server);
    registerContourMapsByBoundingBoxOzone(server);
    registerContourMapsByBoundingBoxPM25(server);
    registerCurrentObservationsByZipCode(server);
    registerCurrentObservationsByLatLong(server);
    registerForecastByLatLong(server);
    registerForecastByZipCode(server);
    registerHistoricalObservationsByLatLong(server);
    registerHistoricalObservationsByZipCode(server);