eBird MCP Server

Instructions

Implementation Reference

• src/index.ts:267-280 (handler)

  The handler function that executes the logic for the get_historic_observations tool. It builds query parameters and makes an API request to eBird's historic observations endpoint.

  async (args) => {
    const params: Record<string, string | number | boolean> = {
      detail: args.detail,
      hotspot: args.hotspot,
      includeProvisional: args.include_provisional,
      rank: args.rank,
      sppLocale: args.spp_locale,
    };
    if (args.cat) params.cat = args.cat;
    if (args.max_results) params.maxResults = args.max_results;
  
    const result = await makeRequest(`/data/obs/${args.region_code}/historic/${args.year}/${args.month}/${args.day}`, params);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/index.ts:255-266 (schema)

  Zod schema defining the input parameters and validation for the get_historic_observations tool.

    region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
    year: z.number().min(1800).describe("Year"),
    month: z.number().min(1).max(12).describe("Month"),
    day: z.number().min(1).max(31).describe("Day of month"),
    cat: z.string().optional().describe("Taxonomic category filter"),
    detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail"),
    hotspot: z.boolean().default(false).describe("Only fetch from hotspots"),
    include_provisional: z.boolean().default(false).describe("Include unreviewed observations"),
    max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"),
    rank: z.enum(["mrec", "create"]).default("mrec").describe("'mrec' for latest, 'create' for first added"),
    spp_locale: z.string().default("en").describe("Language for common names"),
  },

• src/index.ts:251-281 (registration)

  Registration of the get_historic_observations tool on the MCP server using server.tool(), including name, description, schema, and handler function.

  server.tool(
    "get_historic_observations",
    "Get observations from a specific date in history.",
    {
      region_code: z.string().describe("Country, subnational1, subnational2, or location code"),
      year: z.number().min(1800).describe("Year"),
      month: z.number().min(1).max(12).describe("Month"),
      day: z.number().min(1).max(31).describe("Day of month"),
      cat: z.string().optional().describe("Taxonomic category filter"),
      detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail"),
      hotspot: z.boolean().default(false).describe("Only fetch from hotspots"),
      include_provisional: z.boolean().default(false).describe("Include unreviewed observations"),
      max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"),
      rank: z.enum(["mrec", "create"]).default("mrec").describe("'mrec' for latest, 'create' for first added"),
      spp_locale: z.string().default("en").describe("Language for common names"),
    },
    async (args) => {
      const params: Record<string, string | number | boolean> = {
        detail: args.detail,
        hotspot: args.hotspot,
        includeProvisional: args.include_provisional,
        rank: args.rank,
        sppLocale: args.spp_locale,
      };
      if (args.cat) params.cat = args.cat;
      if (args.max_results) params.maxResults = args.max_results;
  
      const result = await makeRequest(`/data/obs/${args.region_code}/historic/${args.year}/${args.month}/${args.day}`, params);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );

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

  Shared helper function used by the tool to make authenticated requests to the eBird API.

  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();
  }