get_nearby_observations

Find recent bird observations near any location using eBird data. Filter by date range, distance, species category, and hotspots to discover local bird sightings.

Instructions

Get recent observations near a geographic location.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`lat`	Yes	Latitude
`lng`	Yes	Longitude
`back`	No	Number of days back to fetch
`cat`	No	Taxonomic category filter
`dist`	No	Search radius in kilometers
`hotspot`	No	Only fetch from hotspots
`include_provisional`	No	Include unreviewed observations
`max_results`	No	Maximum observations to return
`sort`	No	Sort by date or species	date
`spp_locale`	No	Language for common names	en

Implementation Reference

src/index.ts:140-156 (handler)

The asynchronous handler function that implements the core logic of the 'get_nearby_observations' tool. It constructs query parameters from inputs and calls the eBird API's /data/obs/geo/recent endpoint via makeRequest.

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,
    sort: args.sort,
    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/geo/recent", params);
  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
}

src/index.ts:128-139 (schema)

Zod input schema defining parameters for latitude, longitude, search radius, time frame, filters, and sorting for the get_nearby_observations tool.

{
  lat: z.number().min(-90).max(90).describe("Latitude"),
  lng: z.number().min(-180).max(180).describe("Longitude"),
  back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
  cat: z.string().optional().describe("Taxonomic category filter"),
  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"),
  sort: z.enum(["date", "species"]).default("date").describe("Sort by date or species"),
  spp_locale: z.string().default("en").describe("Language for common names"),
},

src/index.ts:125-157 (registration)

MCP server.tool registration for 'get_nearby_observations', including name, description, schema, and handler.

server.tool(
  "get_nearby_observations",
  "Get recent observations near a geographic location.",
  {
    lat: z.number().min(-90).max(90).describe("Latitude"),
    lng: z.number().min(-180).max(180).describe("Longitude"),
    back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"),
    cat: z.string().optional().describe("Taxonomic category filter"),
    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"),
    sort: z.enum(["date", "species"]).default("date").describe("Sort by date or species"),
    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,
      sort: args.sort,
      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/geo/recent", params);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

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

Utility function used by all tools, including get_nearby_observations, to perform authenticated HTTP 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();
}

eBird MCP Server