eBird MCP Server

Instructions

Implementation Reference

• src/index.ts:173-188 (handler)

  Handler function that constructs query parameters from inputs, calls the eBird API endpoint `/data/obs/geo/recent/{species_code}`, and formats the response as JSON text.

    async (args) => {
      const params: Record<string, string | number | boolean> = {
        lat: args.lat,
        lng: args.lng,
        back: args.back,
        dist: args.dist,
        hotspot: args.hotspot,
        includeProvisional: args.include_provisional,
        sppLocale: args.spp_locale,
      };
      if (args.max_results) params.maxResults = args.max_results;
  
      const result = await makeRequest(`/data/obs/geo/recent/${args.species_code}`, params);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );

• src/index.ts:162-172 (schema)

  Zod schema defining input parameters for the tool, including coordinates, species code, time window, distance, and filters.

  {
    lat: z.number().min(-90).max(90).describe("Latitude"),
    lng: z.number().min(-180).max(180).describe("Longitude"),
    species_code: z.string().describe("eBird species code"),
    back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
    dist: z.number().min(0).max(50).default(25).describe("Search radius in kilometers"),
    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:159-189 (registration)

  Tool registration call using McpServer.tool() method, specifying name, description, input schema, and handler function.

  server.tool(
    "get_nearby_species_observations",
    "Get recent observations of a specific species near a location.",
    {
      lat: z.number().min(-90).max(90).describe("Latitude"),
      lng: z.number().min(-180).max(180).describe("Longitude"),
      species_code: z.string().describe("eBird species code"),
      back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
      dist: z.number().min(0).max(50).default(25).describe("Search radius in kilometers"),
      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> = {
        lat: args.lat,
        lng: args.lng,
        back: args.back,
        dist: args.dist,
        hotspot: args.hotspot,
        includeProvisional: args.include_provisional,
        sppLocale: args.spp_locale,
      };
      if (args.max_results) params.maxResults = args.max_results;
  
      const result = await makeRequest(`/data/obs/geo/recent/${args.species_code}`, params);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );

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

  Utility function used by all tools to make authenticated HTTP requests to the eBird API, handling query parameters 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();
  }