README.md•7.46 kB
# ALA API MCP Server
[](https://github.com/AtlasOfLivingAustralia/ala-mcp/actions)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server for interacting with the [Atlas of Living Australia (ALA)](https://www.ala.org.au/) API.
Disclaimer: This is a vibe-coded project and only intended for demonstration and educational purposes for the internal ALA team.
## Quick Start
### Installation
```bash
# 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
```bash
# Run directly
python -m ala_mcp
# Or use the convenience script
./server.py
# Or use make
make run
```
### Configuration with MCP Clients
#### Amazon Q
```bash
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):
```json
{
"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](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](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:
```bash
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
```bash
# Install development dependencies
make install-dev
# Install pre-commit hooks
make pre-commit
```
### Running Tests
```bash
# Run all tests
make test
# Run with coverage report
make test-cov
# Run specific test file
pytest tests/test_client.py
```
### Code Quality
```bash
# 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](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](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](https://api.ala.org.au/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Project Issues](https://github.com/yourusername/ala-mcp/issues)
## Acknowledgments
- Atlas of Living Australia for providing the biodiversity data API
- The MCP community for the protocol specification
- All contributors to this project