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.

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

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

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

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