README.md•6.75 kB
# AviBase MCP Server
[](https://www.npmjs.com/package/@kshayk/avibase-mcp)
[](https://opensource.org/licenses/ISC)
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
```bash
npm install @kshayk/avibase-mcp
```
### Install from source
```bash
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`
```json
{
"mcpServers": {
"avibase": {
"command": "npx",
"args": ["@kshayk/avibase-mcp"]
}
}
}
```
### For other MCP clients
Run the server with stdio transport:
```bash
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**:
```javascript
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
```javascript
// Find all critically endangered raptors
custom_bird_query({
filters: {
Family: "Accipitridae",
IUCN_Red_List_Category: ["CR"]
}
})
```
### Taxonomic Studies
```javascript
// Get all species described by Linnaeus
get_birds_by_authority({authority: "Linnaeus", limit: 100})
```
### Regional Biodiversity
```javascript
// Explore bird diversity in Australia
get_birds_by_region({region: "Australia", limit: 200})
```
### Data Analysis
```javascript
// 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.