eBird MCP Server

Instructions

Implementation Reference

• src/index.ts:355-365 (registration)

  Registration of the 'get_species_list' tool using McpServer.tool method, including name, description, input schema, and execution handler.

  server.tool(
    "get_species_list",
    "Get all species ever recorded in a region (species codes in taxonomic order).",
    {
      region_code: z.string().describe("Any region code (country, subnational, location, etc.)"),
    },
    async (args) => {
      const result = await makeRequest(`/product/spplist/${args.region_code}`);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );

• src/index.ts:361-364 (handler)

  Handler function that fetches the species list from eBird API endpoint `/product/spplist/{region_code}` using the shared makeRequest helper and returns formatted JSON response.

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

• src/index.ts:358-360 (schema)

  Zod schema defining the single input parameter 'region_code' as a string.

  {
    region_code: z.string().describe("Any region code (country, subnational, location, etc.)"),
  },

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

  Shared utility function to make authenticated requests to the eBird API, used by all tools including get_species_list.

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