eBird MCP Server

Instructions

Implementation Reference

• src/index.ts:59-71 (handler)

  The handler function that implements the core logic: maps input args to API params, calls the shared makeRequest helper to query the eBird /data/obs/{region}/recent endpoint, and formats the response as MCP content.

  async (args) => {
    const params: Record<string, string | number | boolean> = {
      back: args.back,
      hotspot: args.hotspot,
      includeProvisional: args.include_provisional,
      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}/recent`, params);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/index.ts:50-58 (schema)

  Zod schema defining the input parameters for the tool, including region_code (required), back (days), optional filters like cat, hotspot, etc.

  {
    region_code: z.string().describe("Country, subnational1, subnational2, or location code (e.g., 'US', 'US-NY', 'US-NY-109', 'L99381')"),
    back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch (1-30)"),
    cat: z.string().optional().describe("Taxonomic category filter (e.g., 'species', 'hybrid')"),
    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"),
    spp_locale: z.string().default("en").describe("Language for common names"),
  },

• src/index.ts:48-72 (registration)

  The server.tool() call that registers the 'get_recent_observations' tool with the MCP server, providing name, description, input schema, and handler function.

    "get_recent_observations",
    "Get recent bird observations in a region (up to 30 days ago). Returns species, location, date, and count info.",
    {
      region_code: z.string().describe("Country, subnational1, subnational2, or location code (e.g., 'US', 'US-NY', 'US-NY-109', 'L99381')"),
      back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch (1-30)"),
      cat: z.string().optional().describe("Taxonomic category filter (e.g., 'species', 'hybrid')"),
      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"),
      spp_locale: z.string().default("en").describe("Language for common names"),
    },
    async (args) => {
      const params: Record<string, string | number | boolean> = {
        back: args.back,
        hotspot: args.hotspot,
        includeProvisional: args.include_provisional,
        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}/recent`, params);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );

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

  Shared helper function used by all tools to construct and make authenticated HTTP requests to the eBird API, handling URL params, auth header, error checking, and JSON parsing.

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