Trello Sync

Bidirectional task synchronization with Trello boards.

Overview

What it does:

• •Pulls task status from Trello cards
• •Pushes local task completions to Trello
• •Keeps both sources in sync automatically

Dual Source of Truth:

• •Trello = task status (done, blocked, active), due dates, assignments
• •Local files = context, notes, history, related files

Required Hooks

Setup Hook

Trigger: "Add Trello integration"

Prerequisites:

• •Node.js (for npx)

MCP Server: @delorenj/mcp-server-trello (Official MCP Registry)

Credential Collection:

Step 1: API Key

Go to: trello.com/power-ups/admin
Create a new Power-Up (any name, like "AnyManage")
Copy your API Key from the page

Step 2: Token

Go to this URL (with your API key):
https://trello.com/1/authorize?expiration=never&name=AgentPM&scope=read,write&response_type=token&key={API_KEY}

Click "Allow"
Copy the token shown

Step 3: Board Selection

Which Trello board should I sync with?
(Lists available boards, user selects one)

Installation (agent executes silently):

Claude Code:

claude mcp add --transport stdio \
  --env TRELLO_API_KEY=${API_KEY} \
  --env TRELLO_TOKEN=${TOKEN} \
  trello -- npx -y @delorenj/mcp-server-trello

opencode (update opencode.json):

{
  "mcp": {
    "trello": {
      "type": "local",
      "command": ["npx", "-y", "@delorenj/mcp-server-trello"],
      "environment": {
        "TRELLO_API_KEY": "${API_KEY}",
        "TRELLO_TOKEN": "${TOKEN}"
      }
    }
  }
}

Verification:

• •Call trello_list_boards to confirm connection
• •Success: "Connected! Try 'sync trello' to see your tasks."
• •Failure: Guide through credential re-entry

Sync Hook

Trigger: "Sync trello", automatic on session start

Pull Operations:

1. •Get cards from configured board
2. •Map card status (list name) to local task checkbox
3. •Map due dates to local metadata
4. •Map labels to local tags

Push Operations:

1. •Detect local task completions (checkbox changes)
2. •Move cards to appropriate Trello list
3. •Add comments for significant updates (optional)

Bidirectional Mapping:

List-to-Checkbox Mapping:

• •"To Do", "Backlog" → [ ]
• •"In Progress", "Doing" → [-]
• •"Done", "Complete" → [x]
• •Custom list names: configurable during setup

Conflict Resolution:

• •Trello wins on true conflict (both changed since last sync)
• •User notified: "Conflict on [task]. Kept Trello version: Done"
• •Local context/notes always preserved

User Communication:

• •Success: "Synced 5 tasks with Trello (3 updated, 2 new)"
• •Partial: "Synced 3/5 tasks. 2 failed due to rate limit - try again shortly."
• •No changes: "Trello is up to date."

Error Hook

Trigger: Any Trello operation failure

Connection Failure:

1. •Log error to ops/logs/agent-actions.log (credentials masked)
2. •Display: "Trello unavailable - working with local data"
3. •Silent retry (5-second delay)
4. •If still failing: Continue local-only
5. •Monitor for recovery (60-second checks)
6. •On recovery: "Trello available. Sync pending changes?"

Rate Limit (429):

• •Trello limits: 300 req/10s per API key, 100 req/10s per token
• •Display: "Trello rate limited. Try again in a few minutes."
• •Queue operations, don't drop them

Auth Failure:

• •Display: "Trello authentication failed. Run 'add trello integration' to reconnect."

Logging Format:

{
  "timestamp": "2026-01-25T10:30:00Z",
  "action": "trello_sync_error",
  "error_type": "connection_failed",
  "credentials": "TRELLO_TOKEN=***",
  "retry_count": 1,
  "fallback": "local_only"
}

Optional Hooks

Status Hook

Trigger: "Check integrations"

Returns:

• •Connection state: connected / unavailable / not configured
• •Last sync: timestamp
• •Board: configured board name
• •Pending changes: count

Display:

Trello: Connected
Last sync: 5 minutes ago
Board: Marketing Tasks
Pending: 0 changes

Configure Hook

Trigger: "Configure trello"

Options:

• •Change board: "Which board should I sync with?"
• •Change list mapping: "Which list means 'done'?"
• •Reconnect: Re-enter credentials

Disconnect Hook

Trigger: "Remove trello integration"

Behavior:

1. •Remove MCP configuration
2. •Update INTEGRATIONS.md to "Not configured"
3. •Confirm: "Trello integration removed. Your local files are unchanged."

Credentials

Rate Limits

In practice: Normal use rarely hits limits. Bulk operations (syncing 100+ tasks) may require pacing.

Data Mapping

Session Startup

When session starts with Trello configured:

1. •Quick health check (3-second timeout)
2. •Report status: Integrations: Trello (connected)
3. •If unavailable: Integrations: Trello (unavailable - using local data)

Don't block session startup for integration check.

Related

• •docs/INTEGRATION_GUIDE.md - Integration overview
• •docs/protocols/integration-framework.md - Protocol details
• •ops/TASK_SYNC_PLAYBOOK.md - Daily workflow guide
• •INTEGRATIONS.md - Current status