eBird Binoculars

A TypeScript monorepo providing a fully-typed eBird API client and an MCP server that exposes bird observation data to AI assistants like Claude.

Package	Description
ebird-binoculars-client	TypeScript client for the eBird API
ebird-binoculars-mcp	MCP server exposing eBird data via stdio or HTTP

Client

Getting Started

npm install ebird-binoculars-client

You'll need an eBird API key.

Usage

import EbirdClient from 'ebird-binoculars-client';

const client = new EbirdClient('your-ebird-api-key');

// Get recent observations in Massachusetts
const observations = await client
  .observations()
  .getRecentRegionalObservations({
    regionCode: 'US-MA',
    options: { back: 7, maxResults: 10 },
  });

// Find nearby notable sightings
const notable = await client
  .observations()
  .getRecentNearbyNotableObservations({
    lat: 42.36,
    lng: -71.06,
    options: { dist: 25 },
  });

// Look up hotspots in a region
const hotspots = await client
  .hotspots()
  .getRegionalHotspots({ regionCode: 'US-CA' });

// Get taxonomy information
const taxonomy = await client.taxonomy().getTaxonomy();

Available API Modules

Module	Access	Examples
Observations	client.observations()	Recent, nearby, notable, and historic observations
Regions	client.regions()	Region info, sub-region lists
Product	client.product()	Species lists, checklists, top 100, regional stats
Hotspots	client.hotspots()	Regional hotspots, nearby hotspots, hotspot info
Taxonomy	client.taxonomy()	Species taxonomy, groups, forms, versions
Geography	client.geography()	Adjacent regions

For the full eBird API reference, see the Postman documentation.

MCP Server

The MCP server exposes 11 eBird tools to AI clients. It supports two transport modes: stdio (local) and HTTP (networked with OAuth 2.0).

Getting Started

npm install -g ebird-binoculars-mcp

Prebuilt binaries are included for macOS (ARM64, x64), Linux (x64), and Windows (x64).

Set your eBird API key:

export EBIRD_API_KEY=your-api-key

Stdio Mode

Start a local stdio MCP server for direct integration with AI clients:

ebird-mcp stdio

Claude Desktop / Claude Code configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ebird-binoculars": {
      "command": "ebird-mcp",
      "args": ["stdio"],
      "env": {
        "EBIRD_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP Server Mode

Start a networked MCP server with OAuth 2.0 authentication:

# Basic usage
ebird-mcp server --port 8080 --client-id my-client --client-secret my-secret

# With custom issuer URL
ebird-mcp server --port 8080 --issuer-url https://mcp.example.com --client-id my-client --client-secret my-secret

Environment variables

Variable	Description
EBIRD_API_KEY	Your eBird API key
MCP_OAUTH_CLIENTS	OAuth clients in id:secret,id:secret format
MCP_ALLOWED_REDIRECT_URIS	Comma-separated allowed OAuth redirect URIs

Connecting a remote MCP client

In Claude, add a custom connector under Settings > Connectors > Add custom connector. Enter the address where the server is hosted, and under Advanced settings, provide the --client-id and --client-secret values you used when starting the server.

Available MCP Tools

Tool	Description
get_sub_region_list	Fetch countries, states, or provinces for a region
get_species_list	All species ever observed in a region
get_recent_regional_observations	Recent observations in a region
get_recent_notable_regional_observations	Recent rare/unusual observations in a region
get_recent_regional_species_observations	Recent observations of a species in a region
get_recent_nearby_observations	Recent observations near a lat/lng
get_recent_nearby_species_observations	Recent observations of a species near a lat/lng
get_nearest_species_observations	Nearest observations of a species to a lat/lng
get_recent_nearby_notable_observations	Recent notable observations near a lat/lng
get_historic_observations_on_date	Historical observations on a specific date
get_checklist	Fetch a checklist by ID

Example Query

Once connected, ask your AI assistant something like:

"What rare birds have been spotted near Central Park in the last week?"

The assistant will use tools like get_recent_nearby_notable_observations with the coordinates for Central Park to find and summarize recent notable sightings.

Development

Requires Bun runtime.

# Install dependencies
bun install

# Build all packages
bun run build

# Run tests (requires EBIRD_API_KEY)
bun test

# Lint
bun run eslint .

# Format
bun run prettier --write .

License

MIT