Trellio - Async Trello API Client for Python

Trellio is a production-ready, asynchronous Python client for the Trello API, built on httpx and pydantic. Designed for use in long-running services like MCP servers, it provides retry with backoff, request timeouts, structured logging, and full CRUD coverage across 10 Trello resource types.

Features

Infrastructure

• Async I/O -- built on httpx.AsyncClient, non-blocking
• Retry with exponential backoff -- automatic retry on 429/5xx, respects Retry-After header, configurable max_retries, initial_delay, backoff_factor
• Request timeout -- configurable per-client, raises TrelloAPIError on timeout
• Pagination -- list_boards(limit, since) for single pages, list_all_boards(page_size) async generator for auto-pagination
• Structured logging -- trellio logger with DEBUG (every request), WARNING (retries), ERROR (failures)
• Typed exceptions -- TrelloAPIError(status_code, message) for all API errors
• Pydantic models -- type-safe response objects with alias support for Trello's camelCase API

Resources (46 client methods)

Models

TrelloMember, TrelloBoard, TrelloList, TrelloCard, TrelloLabel, TrelloChecklist, TrelloCheckItem, TrelloComment, TrelloAttachment, TrelloWebhook, TrelloSearchResult

Quick Start

import asyncio
from trellio import TrellioClient

async def main():
    async with TrellioClient(
        api_key="your_key",
        token="your_token",
        max_retries=3,
        timeout=30.0,
    ) as client:
        boards = await client.list_boards()
        for board in boards:
            print(board.name)

        results = await client.search("project")
        for card in results.cards:
            print(card.name)

asyncio.run(main())

MCP Server Usage

from trellio import TrellioClient, TrelloAPIError

client = TrellioClient(
    api_key=os.environ["TRELLO_API_KEY"],
    token=os.environ["TRELLO_TOKEN"],
    max_retries=3,
    initial_delay=1.0,
    timeout=30.0,
)

# Use in MCP tool handlers:
async def handle_create_card(list_id: str, name: str):
    try:
        card = await client.create_card(list_id, name)
        return {"id": card.id, "name": card.name}
    except TrelloAPIError as e:
        return {"error": e.message, "status": e.status_code}

Philosophy: BDD & Single Source of Truth

This project follows strict Behavior-Driven Development (BDD) where Gherkin feature files are the Single Source of Truth for business logic. All implementation is derivative of the specifications.

Test Coverage

The BDD suite covers 19 features, 144 scenarios, 1048 steps:

Development Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Run BDD suite
PYTHONPATH=src python -m behave

# Run mock validation
PYTHONPATH=src pytest tests/validation/

Quick Start with Make

For a fresh checkout, the simplest path is:

make test

This will:

• create .venv if it does not exist
• install dependencies if they are not available yet
• run the validation tests with pytest
• run the BDD suite with behave

You can also use:

make
make deps
make test-pytest
make test-behave

Architecture Decisions

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.