Skip to main content
Glama

ALA API MCP Server

Official
by AtlasOfLivingAustralia
GitHub
Python
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

ALA API MCP Server

CI codecov Python Version License: MIT

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:

Variable

Default

Description

ALA_BASE_URL

https://biocache-ws.ala.org.au/ws

ALA API base URL

ALA_DEFAULT_TIMEOUT

30

Request timeout in seconds

ALA_LOG_LEVEL

INFO

Logging level

ALA_API_KEY

None

Optional API key for authentication

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

Acknowledgments

  • Atlas of Living Australia for providing the biodiversity data API

  • The MCP community for the protocol specification

  • All contributors to this project

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables interaction with the Atlas of Living Australia API to search and access 152+ million biodiversity records. Supports occurrence searches, spatial queries, bulk data downloads, and taxonomic data retrieval through natural language.

  1. Quick Start
    1. Installation
    2. Running the Server
    3. Configuration with MCP Clients
  2. Usage
    1. Example Requests
  3. Configuration
    1. Using .env file
  4. Development
    1. Setup Development Environment
    2. Running Tests
    3. Code Quality
    4. Available Make Commands
  5. Project Structure
    1. Contributing
      1. License
        1. Troubleshooting
          1. Server fails to start
          2. Tests failing
          3. MCP client connection issues
        2. Resources
          1. Acknowledgments

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/AtlasOfLivingAustralia/ala-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server