Trello Setup

Trello Setup

Connect your Trello boards to Dex so your tasks, projects, and daily plans stay in sync with your Trello Kanban boards.

What This Enables

Once connected, Dex can:

• Task Sync: Cards created in Dex appear on your Trello board; cards moved to Done in Trello mark tasks complete in Dex
• Project Health: See live board status -- cards by list, blocked items, stale cards
• Daily Plan: Surface Trello cards assigned to you, including overdue items
• Meeting Prep: Know which board has blocked cards to discuss with attendees

Privacy

• Card titles and status sync. No attachments or comments are read unless you ask.
• Your API key and token stay local on your machine and are gitignored
• Sync is on-demand (during daily plan or task creation) -- no background polling
• Only boards you explicitly configure are accessed

When to Run

• User types /trello-setup
• User asks about connecting Trello
• User wants Kanban board context in daily plans or project health
• During /integrate-mcp if Trello is mentioned

Setup Flow

Step 1: Check if Already Connected

1. Check System/integrations/config.yaml for a trello: section with enabled: true
2. If found, skip to Step 6 (Configure Board Mapping)
3. If not found, continue to Step 2

Step 2: Explain What We're Setting Up

Say:

**Let's connect Trello to Dex.**

This links your Trello boards so tasks sync between Dex and Trello.
Cards move between lists = status updates in Dex. Simple Kanban sync.

**What you'll need:**
- A Trello account with at least one board
- Your Trello API key and token (I'll walk you through getting these)
- About 3 minutes

**Ready to go?**

Wait for confirmation.

Step 3: Get API Credentials

Walk the user through getting their Trello API key and token:

**Step 1: Get your API Key**

1. Go to https://trello.com/power-ups/admin
2. Click "New" to create a new Power-Up (or use an existing one)
3. Copy your **API Key** from the Power-Up settings

**Step 2: Generate a Token**

1. On the same page, click the link to generate a **Token**
2. Authorize the app when prompted
3. Copy the token that appears

**Paste your API key and token when ready.**

Wait for the user to provide both values.

Step 4: Add the MCP Server

Check the user's MCP configuration. If mcp-server-trello is not listed:

1. Explain what we're adding:

I'll add the Trello connector to your Dex configuration.
This uses mcp-server-trello which runs on Bun for fast performance.

2. Add to the user's .mcp.json:

{
  "mcp-server-trello": {
    "command": "bunx",
    "args": ["-y", "mcp-server-trello"],
    "env": {
      "TRELLO_API_KEY": "<user's api key>",
      "TRELLO_TOKEN": "<user's token>"
    }
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 5: Test the Connection

Run a quick test to confirm everything works:

1. List the user's boards via the Trello MCP
2. Show a brief summary:

**Connection test:**
- Found [N] boards: [Board Name 1], [Board Name 2], ...
- API access confirmed

Everything looks good!

If it fails, troubleshoot:

That didn't work. A few things to check:

1. **API Key correct?** Should be a 32-character string
2. **Token correct?** Should be a longer string (64+ characters)
3. **Account access?** Make sure the token has read/write permissions

Want to re-enter your credentials?

Retry up to 2 times, then offer to skip and come back later.

Step 6: Configure Board Mapping

Ask the user which board to sync:

**Which Trello board should Dex sync with?**

Here are your boards:
1. [Board Name 1]
2. [Board Name 2]
3. [Board Name 3]

Pick a board (or say "show all" for the full list).

You can add more boards later by running `/trello-setup` again.

After they choose a board:

**Now let's map your lists to Dex statuses.**

I'll look at the lists on [Board Name]:
- "To Do" -> Backlog (not started)
- "In Progress" -> Started
- "Review" -> (unmapped -- keep or map to Blocked?)
- "Done" -> Done

Does this mapping look right? Or should I adjust?

Let the user confirm or customize the mapping. Default status list names:

• Backlog / To Do / TODO -> status n
• In Progress / Doing / Active -> status s
• Blocked / On Hold / Waiting -> status b
• Done / Complete / Finished -> status d

Step 7: Trust Level

Ask about sync behavior:

**How should Dex handle Trello sync?**

1. **Auto-sync** — Cards sync automatically during daily plan and task creation
2. **Ask each time** — Dex shows you what changed and asks before syncing

Which do you prefer? (Most people choose auto-sync)

Step 8: Save Configuration

Write to System/integrations/config.yaml -- update the trello section:

trello:
  enabled: true
  task_sync: true
  configured_at: YYYY-MM-DD
  api_key: <user's api key>
  token: <user's token>
  default_board: <board id>
  board_name: <board name>
  trust_level: auto | ask
  list_mapping:
    backlog: <list id for Backlog>
    in_progress: <list id for In Progress>
    blocked: <list id for Blocked>
    done: <list id for Done>
  features:
    task_sync: true
    project_health: true
    daily_plan: true
    meeting_prep: true

If the file already exists, only update the trello: section. Preserve other integration configs.

Step 9: Confirm

**Trello is connected!**

Here's what changes now:

- **Task Sync** — New Dex tasks appear on your [Board Name] board. Cards completed in Trello mark tasks done in Dex.
- **Project Health** (`/project-health`) shows live board status -- cards by list, blocked items
- **Daily Plan** (`/daily-plan`) includes your assigned Trello cards and overdue items
- **Meeting Prep** (`/meeting-prep`) surfaces blocked cards relevant to attendees

**Capability cascade:** These skills now have Trello awareness built in.

You can adjust settings anytime by running `/trello-setup` again.

Troubleshooting

Token Expired

Trello tokens can be set to expire. If you see auth errors:

1. Go to https://trello.com/power-ups/admin
2. Generate a new token
3. Update System/integrations/config.yaml with the new token
4. Restart MCP server

Board Not Found

If the configured board was deleted or renamed:

1. Run /trello-setup to reconfigure
2. Select the new board
3. Remap lists if needed

Rate Limiting

Trello allows 100 requests per 10 seconds. This is generous -- you'd only hit it during bulk sync. If you see rate limit errors, wait 10 seconds and retry.

Cards Not Syncing

Check:

• Is the board ID correct in config.yaml?
• Does the token have write access?
• Are the list names matching? (List mapping is case-insensitive but names must partially match)

Reconfiguration

If the user runs /trello-setup when already configured:

1. Show current config from System/integrations/config.yaml
2. Offer options:
   • Change synced board
   • Update list mapping
   • Change trust level (auto/ask)
   • Re-authenticate (new API key/token)
   • Add additional boards
   • Disconnect Trello

Disconnect Flow

If user wants to disconnect:

1. Update System/integrations/config.yaml:

   trello:
     enabled: false
   

2. Confirm: "Trello is disconnected. Your daily plans and project health will no longer include Trello context. Run /trello-setup anytime to reconnect."