agentmorris/gbif-mcp-server

GBIF BigQuery MCP Server

A Model Context Protocol (MCP) server that provides AI agents with domain-specific tools for querying GBIF (Global Biodiversity Information Facility) species occurrence data via BigQuery. This MCP server is responsible for query formulation; it relies on the BigQuery MCP server for query execution.

What it Does

This MCP server acts as a bridge between AI agents and GBIF, providing three key capabilities:

• Count occurrences by taxonomic group and geographic location
• Retrieve occurrence records with full details and coordinates
• List species within higher taxonomic groups

The server generates optimized BigQuery SQL with knowledge of:

• GBIF schema and field names
• Common query patterns and best practices
• Taxonomic filtering
• Geographic filtering by ISO country codes

Architecture

AI Agent → GBIF MCP Server → BigQuery MCP Server → Google BigQuery

The MCP generates domain-specific SQL, the BigQuery MCP executes it, and the agent gets results with full GBIF context.

Prerequisites

• Python 3.8+
• BigQuery MCP server

Installation

Create Environment

mamba create -n gbif-mcp-server python=3.12 -2
mamba activate gbif-mcp-server

Install Dependencies

pip install -r requirements.txt

Test Installation

python gbif_mcp_server.py

The server should start and wait for input (Ctrl+C to exit).

Configuration

Configuration varies by your host agent environment, but the relevant .json configuration will look like:

{
  "mcpServers": {
    "gbif-mcp-server": {
      "command": "/path/to/your/gbif-mcp-server/bin/python",
      "args": ["/path/to/your/gbif_mcp_server.py"],
      "env": {}
    },
    "bigquery": {
      "command": "npx",
      "args": ["-y", "@google-cloud/mcp-server-bigquery"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json"
      }
    }
  }
}

Usage Examples

Count Records

"Count mosquito occurrences in Uganda with coordinates"

→ Generates SQL using family = 'Culicidae', country_code = 'UG', require_coordinates = True

Get Species List

"List butterfly species found in Kenya"

→ Generates SQL using order = 'Lepidoptera', country_code = 'KE'

Get Occurrence Records

"Get recent bird observations from Brazil, limit 50 records"

→ Generates SQL using class = 'Aves', country_code = 'BR', limit = 50

Available Tools

count_occurrences_by_taxon

Counts GBIF occurrence records by taxonomic group and location.

Parameters:

• kingdom, phylum, class_name, order, family, genus, species: Taxonomic filters
• country_code: Two-letter ISO country code (e.g., 'UG', 'KE')
• require_coordinates: Only count records with valid coordinates
• min_year, max_year: Temporal filters

get_occurrence_records

Retrieves actual occurrence records with full details.

Parameters: Same as above, plus:

• limit: Maximum records to return (default 100, max 10,000)

get_species_in_taxon

Lists distinct species within a higher taxonomic group.

Parameters: Same as count tool, minus species-level filtering

• limit: Maximum species to return (default 1,000)

Resources

The server also provides reference resources:

• gbif://schema: GBIF BigQuery schema reference
• gbif://country-codes: Common ISO country codes

Example SQL Output

Input: "Count mosquito records in Uganda with coordinates"

Generated SQL:

SELECT COUNT(*) as occurrence_count
FROM `bigquery-public-data.gbif.occurrences`
WHERE occurrencestatus = 'PRESENT' 
  AND UPPER(family) = UPPER('Culicidae') 
  AND countrycode = 'UG' 
  AND decimallatitude IS NOT NULL 
  AND decimallongitude IS NOT NULL;

Data Source

This server generates queries for the GBIF BigQuery dataset, which contains over 2 billion species occurrence records from the Global Biodiversity Information Facility.

License

MIT License