Paraguayan Birding Assistant

A Model Context Protocol server about birdwatching in Paraguay, built with the official Python SDK using FastMCP.

It connects to the eBird API to help you discover birds and great places to watch them across Paraguay.

It exposes:

• a paraguay_birds tool that lists recent bird observations reported in Paraguay
• a paraguay_species tool that lists every bird species ever recorded in Paraguay (with common and scientific names)
• a recommend_birding_spots tool that recommends nearby eBird hotspots, ranked by how many species have been seen there

Requirements

• uv (Python project/dependency manager)
• Python 3.11+ (uv installs this automatically)
• An eBird API key, passed via the --ebird-api-key argument (or the EBIRD_API_KEY environment variable)

Setup

Dependencies are managed with uv and declared in pyproject.toml:

uv sync

Standalone MCP development tools

The SDK ships a standalone mcp CLI. Run it through uv:

uv run mcp            # show available commands
uv run mcp version    # show the installed MCP version

Development mode (MCP Inspector)

The fastest way to test and debug the server is with the MCP Inspector. Because the mcp CLI doesn't forward the --ebird-api-key argument, set the API key via the environment variable first:

export EBIRD_API_KEY=YOUR_EBIRD_API_KEY
uv run mcp dev server.py

Run the server directly

Pass your eBird API key with --ebird-api-key:

uv run server.py --ebird-api-key YOUR_EBIRD_API_KEY

Alternatively, set it once via the environment variable:

export EBIRD_API_KEY=YOUR_EBIRD_API_KEY
uv run server.py

This starts the server with the streamable HTTP transport on http://localhost:8000/mcp.

Test with the MCP Inspector (alternative)

Start the server as above, then in a separate terminal:

npx -y @modelcontextprotocol/inspector

Connect to http://localhost:8000/mcp in the inspector UI.