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

# Clone the repository
git clone https://github.com/yourusername/ala-mcp.git
cd ala-mcp

# Install in development mode with all dependencies
make install-dev

# Or use pip directly
pip install -e ".[dev]"

Running the Server

# Run directly
python -m ala_mcp

# Or use the convenience script
./server.py

# Or use make
make run

Configuration with MCP Clients

Amazon Q

q mcp add --name ala-api \
  --command /path/to/venv/bin/python \
  --args /path/to/ala-mcp/src/ala_mcp/__main__.py

Claude Desktop

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

{
  "mcpServers": {
    "ala-api": {
      "command": "/absolute/path/to/ala-mcp/venv/bin/python",
      "args": ["-m", "ala_mcp"],
      "env": {}
    }
  }
}

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:

ALA_BASE_URL=https://biocache-ws.ala.org.au/ws
ALA_LOG_LEVEL=DEBUG
ALA_API_KEY=your-api-key-here

Development

Setup Development Environment

# Install development dependencies
make install-dev

# Install pre-commit hooks
make pre-commit

Running Tests

# Run all tests
make test

# Run with coverage report
make test-cov

# Run specific test file
pytest tests/test_client.py

Code Quality

# Format code
make format

# Run linting
make lint

# Run type checking
make type-check

# Run security checks
make security

# Run everything
make all

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

ala-mcp/
├── .github/
│   └── workflows/          # CI/CD workflows
├── src/
│   └── ala_mcp/
│       ├── __init__.py     # Package initialization
│       ├── __main__.py     # Entry point
│       ├── server.py       # MCP server implementation
│       ├── client.py       # ALA API client
│       ├── config.py       # Configuration management
│       └── logging_config.py # Logging setup
├── tests/                  # Test suite
│   ├── conftest.py        # Test fixtures
│   ├── test_server.py     # Server tests
│   ├── test_client.py     # Client tests
│   └── test_config.py     # Config tests
├── pyproject.toml         # Project metadata and dependencies
├── Makefile               # Development commands
└── README.md              # This file

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