birdwatching-mcp

# Paraguayan Birding Assistant A [Model Context Protocol](https://modelcontextprotocol.io) server about **birdwatching in Paraguay**, built with the official [Python SDK](https://github.com/modelcontextprotocol/python-sdk) using `FastMCP`. It connects to the [eBird API](https://documenter.getpostman.com/view/664302/S1ENwy59) 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](https://docs.astral.sh/uv/) (Python project/dependency manager) - Python 3.11+ (uv installs this automatically) - An [eBird API key](https://ebird.org/api/keygen), 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`: ```bash uv sync ``` ## Standalone MCP development tools The SDK ships a standalone `mcp` CLI. Run it through uv: ```bash 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: ```bash 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`: ```bash uv run server.py --ebird-api-key YOUR_EBIRD_API_KEY ``` Alternatively, set it once via the environment variable: ```bash 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: ```bash npx -y @modelcontextprotocol/inspector ``` Connect to `http://localhost:8000/mcp` in the inspector UI.