get_regional_statistics

Retrieve bird observation statistics for a specific region and date, including checklist counts, species counts, and contributor numbers from eBird data.

Instructions

Get statistics for a region on a specific date (checklist count, species count, contributor count).

Input Schema

TableJSON Schema

Name	Required	Description
`region_code`	Yes	Country, subnational1, subnational2, or location code
`year`	Yes	Year
`month`	Yes	Month
`day`	Yes	Day of month

Implementation Reference

src/index.ts:349-352 (handler)

Handler function that makes an API request to eBird's /product/stats endpoint with region and date parameters, then returns the JSON response as text content.

async (args) => {
  const result = await makeRequest(`/product/stats/${args.region_code}/${args.year}/${args.month}/${args.day}`);
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
}

src/index.ts:343-348 (schema)

Zod schema defining input parameters: region_code (string), year (number), month (number 1-12), day (number 1-31).

{
  region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
  year: z.number().describe("Year"),
  month: z.number().min(1).max(12).describe("Month"),
  day: z.number().min(1).max(31).describe("Day of month"),
},

src/index.ts:340-353 (registration)

MCP server tool registration for 'get_regional_statistics', including name, description, input schema, and inline handler function.

server.tool(
  "get_regional_statistics",
  "Get statistics for a region on a specific date (checklist count, species count, contributor count).",
  {
    region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
    year: z.number().describe("Year"),
    month: z.number().min(1).max(12).describe("Month"),
    day: z.number().min(1).max(31).describe("Day of month"),
  },
  async (args) => {
    const result = await makeRequest(`/product/stats/${args.region_code}/${args.year}/${args.month}/${args.day}`);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

src/index.ts:19-36 (helper)

Shared helper function used by the tool (and others) to make authenticated requests to the eBird API, handling URL params and error checking.

async function makeRequest(endpoint: string, params: Record<string, string | number | boolean> = {}): Promise<unknown> {
  const url = new URL(`${BASE_URL}${endpoint}`);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined && value !== null) {
      url.searchParams.append(key, String(value));
    }
  });

  const response = await fetch(url.toString(), {
    headers: { "X-eBirdApiToken": API_KEY! },
  });

  if (!response.ok) {
    throw new Error(`eBird API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

eBird MCP Server