AviBase MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to comprehensive bird data through the AviBase dataset. This server acts as a bridge between AI assistants and bird taxonomic, conservation, and geographic data.

🦅 Overview

The AviBase MCP Server gives AI assistants access to a comprehensive bird database containing:

• 40,000+ bird records with taxonomic classification
• IUCN Red List conservation statuses
• Geographic distribution data
• Taxonomic authority information
• Extinction status and historical data
• Advanced query capabilities with JSONata

🚀 Installation

Prerequisites

• Node.js (version 14 or higher)
• npm or yarn package manager

Install via npm

npm install @kshayk/avibase-mcp

Install from source

git clone <repository-url>
cd mcp-package
npm install

⚙️ Configuration

For Claude Desktop

Add the server to your Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "avibase": {
      "command": "npx",
      "args": ["@kshayk/avibase-mcp"]
    }
  }
}

For other MCP clients

Run the server with stdio transport:

node mcp-server.js

🛠️ Available Tools

1. get_bird_stats

Get comprehensive statistics about the bird dataset.

Usage: get_bird_stats()

Returns: Total records, species count, families, orders, conservation categories

2. search_birds

Search for birds by scientific or common name with fuzzy matching.

Parameters:

• query (required): Search term for bird name
• exact (optional): Use exact matching (default: false)
• limit (optional): Maximum results (default: 20)

Example: search_birds({query: "eagle", limit: 10})

3. get_birds_by_taxonomy

Filter birds by taxonomic classification.

Parameters:

• level (required): Taxonomic level ("Order", "Family", or "Taxon_rank")
• value (required): Value to filter by (e.g., "Strigiformes" for owls)
• limit (optional): Maximum results (default: 50)

Example: get_birds_by_taxonomy({level: "Order", value: "Strigiformes"})

4. get_conservation_status

Get birds by IUCN Red List conservation status.

Parameters:

• category (required): IUCN category (CR, EN, VU, NT, LC, DD, EX, EW)
• limit (optional): Maximum results (default: 50)

Example: get_conservation_status({category: "CR"}) (Critically Endangered)

5. get_birds_by_region

Find birds by geographic region or range.

Parameters:

• region (required): Geographic region to search
• limit (optional): Maximum results (default: 50)

Example: get_birds_by_region({region: "Madagascar"})

6. get_extinct_species

Get all extinct or possibly extinct bird species.

Parameters:

• limit (optional): Maximum results (default: 100)

7. get_birds_by_authority

Find birds described by a specific taxonomic authority.

Parameters:

• authority (required): Name of the taxonomic authority
• limit (optional): Maximum results (default: 50)

Example: get_birds_by_authority({authority: "Linnaeus"})

8. get_random_birds

Get a random sample of birds for exploration.

Parameters:

• count (optional): Number of random birds (default: 10, max: 50)

9. get_bird_report

Get a detailed report for a specific bird species.

Parameters:

• scientific_name (required): Scientific name of the bird

Example: get_bird_report({scientific_name: "Aquila chrysaetos"})

10. custom_bird_query

Perform complex queries with multiple filters.

Parameters:

• filters (required): Object with field-value pairs for filtering
• limit (optional): Maximum results (default: 50)

Example:

custom_bird_query({
  filters: {
    Family: "Accipitridae",
    IUCN_Red_List_Category: ["CR", "EN"]
  }
})

11. execute_jsonata_query

Execute raw JSONata queries for advanced data analysis.

Parameters:

• query (required): JSONata query expression
• limit (optional): Maximum results for arrays (default: 50)

Example: execute_jsonata_query({query: "$count($[Taxon_rank = \"species\"])"})

📊 Data Coverage

IUCN Conservation Categories

• CR: Critically Endangered
• EN: Endangered
• VU: Vulnerable
• NT: Near Threatened
• LC: Least Concern
• DD: Data Deficient
• EX: Extinct
• EW: Extinct in the Wild

Taxonomic Coverage

• All major bird orders and families
• Species, subspecies, and other taxonomic ranks
• Historical taxonomic authorities
• Type localities and original descriptions

Geographic Coverage

• Worldwide distribution data
• Regional filtering capabilities
• Range descriptions and habitat information

🔍 Example Use Cases

Conservation Research

// Find all critically endangered raptors
custom_bird_query({
  filters: {
    Family: "Accipitridae",
    IUCN_Red_List_Category: ["CR"]
  }
})

Taxonomic Studies

// Get all species described by Linnaeus
get_birds_by_authority({authority: "Linnaeus", limit: 100})

Regional Biodiversity

// Explore bird diversity in Australia
get_birds_by_region({region: "Australia", limit: 200})

Data Analysis

// Count endangered species by family
execute_jsonata_query({
  query: "$reduce($[IUCN_Red_List_Category = \"EN\"], function($acc, $val) { ($acc[$.Family] := ($acc[$.Family] ? $acc[$.Family] : 0) + 1; $acc) }, {})"
})

🌐 API Endpoint

The server connects to: http://shayk.dev/avibase-mcp

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🙏 Acknowledgments

• AviBase for providing comprehensive bird data
• Model Context Protocol team for the MCP framework
• The birding and ornithology community for their contributions to avian science

📞 Support

For issues, questions, or contributions, please:

• Open an issue on GitHub
• Contact: Shay Kintzlinger

Note: This MCP server requires an internet connection to access the AviBase API endpoints.