# birdnet-mcp

An MCP server that lets LLM clients such as Claude query a [BirdNET-Go](https://github.com/tphakala/birdnet-go) bird-detection instance. It runs over stdio, talks to BirdNET-Go's `/api/v2` HTTP API, and never writes anything — no database access, no mutations.

Ask questions like "what birds were heard this morning?", "when did the first Wood Thrush of the year arrive?", or "which species are most active at dawn?" and let the client compose answers from the tools below.

## Requirements

- A BirdNET-Go instance recent enough to serve `/api/v2` (check `http://your-host:8080/api/v2/health`)
- [uv](https://docs.astral.sh/uv/)

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `BIRDNET_GO_URL` | yes | Base URL of the instance, e.g. `http://birdnet.local:8080` |
| `BIRDNET_GO_TIMEOUT` | no | HTTP timeout in seconds (default 10) |

The server sends no credentials. BirdNET-Go's read endpoints are public by default, and its bearer tokens expire hourly, so there is no durable secret to configure. If your instance has authentication or private mode enabled, allow your network in its config via `security.allowsubnetbypass`.

## Install

### Claude Code

```sh
claude mcp add birdnet -e BIRDNET_GO_URL=http://birdnet.local:8080 \
  -- uv run --directory /path/to/birdnet-mcp birdnet-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "birdnet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/birdnet-mcp", "birdnet-mcp"],
      "env": { "BIRDNET_GO_URL": "http://birdnet.local:8080" }
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `get_recent_detections` | Latest detections |
| `get_detections` | Detections for a day, hour window, or species |
| `search_detections` | Historical search by species, date range, confidence, verification status, and time of day |
| `get_detection` | Full detail for one detection, with audio and spectrogram URLs |
| `get_species_summary` | Per-species counts, first/last heard, and average confidence |
| `get_new_species` | Species first detected within a recent period |
| `get_activity_pattern` | Detection counts per day, or per hour for one day |
| `get_species_info` | Rarity and taxonomy for a scientific name |
| `get_instance_status` | Reachability and health of the instance |

Dates use `YYYY-MM-DD`. Analytics are calendar-day granularity — a BirdNET-Go API limitation.

## Development

```sh
uv sync            # install dependencies
uv run pytest      # run tests
uv run ruff check  # lint
```

To exercise the server against a real instance:

```sh
BIRDNET_GO_URL=http://birdnet.local:8080 npx @modelcontextprotocol/inspector uv run birdnet-mcp
```

## Troubleshooting

- **"Cannot reach BirdNET-Go"** — verify `BIRDNET_GO_URL` and that the web UI loads from the machine running the MCP server.
- **HTTP 401/403** — your instance has authentication or private mode enabled; allow your network via `security.allowsubnetbypass`.
- **Timeouts** — raise `BIRDNET_GO_TIMEOUT`.
- **"Today" looks off by a day** — the server computes today's date in its own local timezone; a remote instance in another timezone may disagree near midnight.