ALA API MCP Server

A Model Context Protocol (MCP) server for interacting with the Atlas of Living Australia (ALA) API.

Disclaimer: This is a vibe-coded project and only intended for demonstration and educational purposes for the internal ALA team.

Quick Start

Installation

Running the Server

Configuration with MCP Clients

Amazon Q

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Important:

• Use the absolute path to your venv's Python (e.g., /Users/username/Projects/ala-mcp/venv/bin/python)

• The -m ala_mcp argument runs the package as a module

• Do NOT use just python - it won't be found in Claude Desktop's PATH

Usage

The server exposes 7 MCP tools for interacting with the Atlas of Living Australia API:

1. search_occurrences - Search 152+ million biodiversity records with filtering and spatial search

2. get_occurrence - Get detailed information about a specific occurrence by UUID

3. download_occurrences - Request bulk data downloads (sent via email)

4. count_taxa - Get occurrence counts for taxa lists

5. create_query_id - Create cached query IDs for complex searches

6. get_query - Retrieve stored query parameters

7. api_request - Advanced: Direct API access for custom requests

For a complete list of available endpoints and examples, see API_ENDPOINTS.md.

Example Requests

Search for occurrences using search_occurrences tool:

MCP clients will see this tool with parameters:

• query (required): Search term (e.g., "Eucalyptus", ":")

• filters (optional): Array of filter queries

• pageSize (optional): Results per page (default: 10)

• lat, lon, radius (optional): Spatial search

• facets (optional): Facet fields for aggregation

Get specific occurrence using get_occurrence tool:

Simply provide the UUID:

• uuid (required): The occurrence record identifier

Download data using download_occurrences tool:

Parameters:

• query (required): Search query

• email (required): Email for download notification

• reasonTypeId (required): Download reason code (e.g., "10" for testing)

• fields (required): Comma-separated field list

• filters (optional): Filter queries

• fileType (optional): "csv" or "tsv" (default: csv)

Advanced users can use api_request tool:

For direct API access with custom parameters:

• method: GET, POST, PUT, DELETE

• endpoint: API path

• params: Query parameters

• data: Request body

• headers: Custom headers

See API_ENDPOINTS.md for comprehensive endpoint documentation and more examples.

Configuration

The server can be configured using environment variables:

Using .env file

Create a .env file in the project root:

Development

Setup Development Environment

Running Tests

Code Quality

Available Make Commands

Run make help to see all available commands:

• make install - Install production dependencies

• make install-dev - Install development dependencies

• make test - Run tests

• make test-cov - Run tests with coverage

• make lint - Run linting

• make format - Format code

• make type-check - Run type checking

• make security - Run security checks

• make clean - Clean build artifacts

• make run - Run the server

• make build - Build distribution packages

Project Structure

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Code of Conduct

• Development workflow

• Submitting pull requests

• Coding standards

License

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

Troubleshooting

Server fails to start

1. Ensure dependencies are installed: pip install -e ".[dev]"

2. Check Python version: python --version (requires 3.10+)

3. Verify virtual environment is activated

Tests failing

1. Install test dependencies: pip install -e ".[dev]"

2. Clear cache: make clean

3. Check for import errors: python -c "import ala_mcp"

MCP client connection issues

1. Verify server path in configuration

2. Check server logs for errors

3. Test server manually: python -m ala_mcp

Resources

• Atlas of Living Australia API Documentation

• Model Context Protocol Specification

• Project Issues

Acknowledgments

• Atlas of Living Australia for providing the biodiversity data API

• The MCP community for the protocol specification

• All contributors to this project