@asapo/trello-mcp-server

A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Trello API to manage cards, lists, and labels on your Trello boards. Perfect for project management automation and team collaboration workflows.

Features

• ✨ Card Management: Create, read, and search cards with full control over position, due dates, members, labels, and location data
• 📑 Template Cards: Copy an existing (template) card so Trello carries description, labels, checklists and custom field values over for you
• 📋 List Management: Create and retrieve lists from boards with position control
• 🏷️ Label Management: Create and retrieve labels with color customization
• ☑️ Checklist Management: Create checklists with seeded items, add/update/reorder items, mark complete/incomplete
• 🔗 Card Cross-Linking: Attach URLs (or other Trello cards) so they appear as preview chips in the sidebar
• 📎 File Attachments: Upload local files (images, PDFs, logs) directly to cards
• 💬 Comment Integration: Add comments to cards for status updates and team communication
• 🔍 Advanced Search: Search cards across boards or within specific projects with flexible query options
• 📊 Board Analysis: Access board information and analyze project structures
• 🖥️ CLI & Scripting: Run every tool from the terminal with npx, or chain calls in a JSON script
• ⚡ High Performance: Optimized API calls with comprehensive field selection
• 🔒 Secure Authentication: Environment-based API key and token management

Installation

Install the package globally to use with Claude Desktop or Claude Code:

npm install -g @asapo/trello-mcp-server

Or install locally for development:

npm install @asapo/trello-mcp-server

Configuration

Get Trello API Credentials

1. Get your API key from: https://trello.com/app-key
2. Generate a token using your API key at: https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=MCP%20Server&key=YOUR_API_KEY

Environment Setup

Set your Trello credentials as environment variables:

export TRELLO_API_KEY=your_trello_api_key_here
export TRELLO_TOKEN=your_trello_token_here

Or create a .env file:

TRELLO_API_KEY=your_trello_api_key_here
TRELLO_TOKEN=your_trello_token_here

Usage

Quick Setup with Claude MCP

From npm Package

The easiest way to add this server to Claude Desktop or Claude Code:

claude mcp add trello @asapo/trello-mcp-server \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Get your Trello API credentials:

• TRELLO_API_KEY: Get from https://trello.com/app-key
• TRELLO_TOKEN: Generate at https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=MCP%20Server&key=YOUR_API_KEY

From Local Clone

If you've cloned the repository for development:

# Clone and setup
git clone [email protected]:wachterjohannes/trello-mcp.git
cd trello-mcp
npm install
npm run build

# Add to Claude with environment variables
claude mcp add trello node $(pwd)/build/index.js \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Or with absolute path:

claude mcp add trello node /absolute/path/to/trello-mcp/build/index.js \
  -e TRELLO_API_KEY=your_api_key_here \
  -e TRELLO_TOKEN=your_token_here

Manual Claude Desktop Integration

Alternatively, manually add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trello": {
      "command": "npx",
      "args": ["@asapo/trello-mcp-server"],
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}

Manual Claude Code Integration

Alternatively, manually add to your ~/.claude/settings.json:

{
  "mcp": {
    "servers": {
      "trello": {
        "command": "npx",
        "args": ["@asapo/trello-mcp-server"],
        "env": {
          "TRELLO_API_KEY": "your_api_key_here",
          "TRELLO_TOKEN": "your_token_here"
        }
      }
    }
  }
}

CLI Usage

Every tool is also available on the command line — no MCP client required. The CLI and the MCP server share one tool registry, so tool names and arguments are identical in both.

npm install -g @asapo/trello-mcp-server
trello setup                                     # authenticate + install the agent skill
trello get_board_lists 507f1f77bcf86cd799439011

Without a global install, run any command through npx -p @asapo/trello-mcp-server trello <...>.

Setup and authentication

trello setup walks through connecting a Trello account: it links to https://trello.com/app-key for the API key, builds the authorization URL for a read/write token, verifies both against the Trello API, and stores them in ~/.config/trello-cli/credentials.json with 0600 permissions (token input is masked while typing). It then installs the agent skill.

trello setup                                  # interactive
trello setup --api-key <key> --token <token>  # non-interactive, e.g. in CI
trello setup --reauth                         # replace stored credentials
trello setup --no-agent-skills                # authenticate only
trello setup --no-auth                        # install/refresh the skill only
trello setup --dry-run                        # verify and report, write nothing

Credential lookup order: TRELLO_API_KEY / TRELLO_TOKEN in the environment (including a .env file in the working directory), then the stored credentials. The MCP server uses the same order, so trello setup also covers it. Nothing is written if verification fails.

Agent skills

The package bundles a Claude Code skill, skills/trello-cli, that teaches an agent to drive this CLI — discovery, argument shapes, when to script, and which operations to confirm first. It is installed into every agent root directory that exists (~/.claude, ~/.agents, plus CLAUDE_CONFIG_DIR when set):

• automatically on a global install (npm install -g), and again on npm install -g <pkg>@latest or npm update -g <pkg>, which is how the skill is refreshed — npm has no separate update hook;
• on demand with trello setup (or trello setup --no-auth for skills only).

Directories are never created implicitly, local (non-global) installs never write to your home directory, and TRELLO_NO_AGENT_SKILLS=1 disables the automatic install entirely. Use --dir <path> to install somewhere else.

Discovering tools

trello list             # all 24 tools with a one-line description
trello help create_card # arguments, types and which ones are required

Calling a tool

Required arguments can be passed positionally (in the order shown by trello help <tool>); everything else is a flag:

trello add_card_comment abc123 "Deployed to staging"

trello create_card \
  --idList 507f191e810c19729de860ea \
  --name "Implement new feature" \
  --desc "Add authentication system" \
  --pos top \
  --due 2024-12-31T23:59:59.000Z \
  --idLabels labelId1,labelId2

Flags follow the tool's JSON schema:

| Argument type | How to pass it | |---------------|----------------| | string | --name "Fix login" | | number | --pos 3 | | boolean | --dueComplete, --dueComplete=false, or --no-closed | | ID lists | --idLabels a,b or repeated --idLabels a --idLabels b | | text lists | repeat the flag: --items "Step one" --items "Step two" | | nullable | --due null to clear a due date |

Flag names also accept kebab-case (--board-id works as well as --boardId), and a whole argument object can be passed as JSON:

trello update_card --json '{"cardId":"abc123","name":"Renamed","pos":"top"}'

Results are printed to stdout as JSON, so they pipe into jq:

trello get_board_cards <boardId> --compact | jq '.[] | select(.due != null) | .name'

Global options: --dry-run (print the resolved call without executing it), --compact (single-line JSON), --help, --version.

Scripts

Multiple calls can be chained in a JSON script and executed top to bottom, with later steps referencing earlier results:

{
  "name": "Sprint setup",
  "steps": [
    {
      "id": "list",
      "tool": "create_list",
      "args": { "name": "Sprint 42", "idBoard": "{{env.TRELLO_BOARD_ID}}", "pos": "top" }
    },
    {
      "id": "card",
      "tool": "create_card",
      "args": { "idList": "{{list.id}}", "name": "Sprint 42 kickoff" }
    },
    {
      "tool": "create_checklist",
      "args": {
        "idCard": "{{card.id}}",
        "name": "Preparation",
        "items": ["Groom the backlog", "Confirm capacity"]
      }
    }
  ]
}

trello run sprint-setup.json            # execute it
trello run sprint-setup.json --dry-run  # validate and preview, no API calls
cat sprint-setup.json | trello run -    # read from stdin

• A step with an "id" is referenced by later steps as {{id.path.to.value}} ({{steps.id...}} also works); environment variables are {{env.NAME}}.
• A placeholder that fills a whole string keeps the original value's type; embedded placeholders are interpolated as text.
• Unknown tools, duplicate ids and forward references are rejected before the first API call.
• The run stops at the first failing step unless --continue-on-error is given; progress goes to stderr (silence it with --quiet), and the array of step results goes to stdout.

A complete example lives in examples/sprint-setup.json.

Available Tools

create_card

Create a new card in a Trello list with full parameter support.

// Parameters
{
  "idList": "string",       // Required: Trello list ID
  "name": "string",         // Required: Card title
  "desc": "string?",        // Optional: Card description (supports Markdown)
  "pos": "number|'top'|'bottom'?", // Optional: Position in list
  "due": "string?",         // Optional: Due date (ISO 8601 format)
  "dueComplete": "boolean?", // Optional: Due date completion status
  "idMembers": "string[]?", // Optional: Array of member IDs to assign
  "idLabels": "string[]?",  // Optional: Array of label IDs to attach
  "urlSource": "string?",   // Optional: URL to create card from
  "address": "string?",     // Optional: Physical address
  "locationName": "string?", // Optional: Location name
  "coordinates": "string?"  // Optional: Geographic coordinates (lat,lng)
}

copy_card

Create a card as a copy of an existing one — the way to use a template card. Trello copies description, labels, checklists and custom field values itself, so nothing has to be transcribed.

// Parameters
{
  "idCardSource": "string",  // Required: ID of the card to copy (e.g. a template card)
  "idList": "string",        // Required: Trello list ID for the copy
  "name": "string?",         // Optional: Title of the copy (defaults to the source card's title)
  "desc": "string?",         // Optional: Description, replacing the source card's (Markdown)
  "pos": "number|'top'|'bottom'?", // Optional: Position in list
  "keepFromSource": "string?" // Optional: 'all' (default) or a comma-separated subset of
                              // attachments, checklists, comments, customFields, due, labels,
                              // members, start, stickers
}

Members and due dates are copied only if keepFromSource says so — with the default all, they are. Pass an explicit subset to leave them behind:

trello copy_card <templateCardId> <listId> \
  --name "Documentation URL per Role" \
  --keep-from-source checklists,customFields,labels

--desc replaces the template's description while the copy still carries its labels, checklists and custom field values — so a filled card is one write, not a create followed by an update.

idCardSource accepts the short link from a https://trello.com/c/<shortLink> URL as well as the full ID — the CLI resolves it, where the Trello API itself answers a short link with a bare Invalid objectId.

Cards carry isTemplate in every read (get_board_cards, get_card_details, search_cards), so a board's template cards are discoverable rather than a hard-coded ID.

update_card

Update an existing Trello card. All fields are optional except cardId.

// Parameters
{
  "cardId": "string",       // Required: Card ID to update
  "name": "string?",        // Optional: New card title
  "desc": "string?",        // Optional: New description (supports Markdown)
  "closed": "boolean?",     // Optional: Archive status (true/false)
  "idList": "string?",      // Optional: Move to different list
  "idMembers": "string[]?", // Optional: Replace assigned members
  "idLabels": "string[]?",  // Optional: Replace attached labels
  "pos": "number|'top'|'bottom'?", // Optional: New position
  "due": "string|null?",    // Optional: Due date or null to remove
  "dueComplete": "boolean?", // Optional: Mark due date complete
  "subscribed": "boolean?", // Optional: Subscribe to updates
  "address": "string?",     // Optional: Physical address
  "locationName": "string?", // Optional: Location name
  "coordinates": "string?"  // Optional: Geographic coordinates (lat,lng)
}

get_board_cards

Retrieve all cards from a specific Trello board with comprehensive metadata.

// Parameters
{
  "boardId": "string" // Trello board ID
}

get_card_details

Get detailed information about a specific card including members, checklists, and attachments.

// Parameters
{
  "cardId": "string" // Trello card ID
}

get_card_comments

Fetch all comments and discussion history for a card.

// Parameters
{
  "cardId": "string" // Trello card ID
}

add_card_comment

Post a new comment to a Trello card for team collaboration.

// Parameters
{
  "cardId": "string", // Trello card ID
  "comment": "string" // Comment text to add
}

search_cards

Search for cards across boards or within specific projects.

// Parameters
{
  "query": "string",     // Search query
  "boardId": "string?"   // Optional: limit to specific board
}

get_board_lists

Retrieve all lists from a Trello board.

// Parameters
{
  "boardId": "string" // Trello board ID
}

create_list

Create a new list on a Trello board.

// Parameters
{
  "name": "string",         // Required: List name
  "idBoard": "string",      // Required: Trello board ID
  "pos": "number|'top'|'bottom'?" // Optional: Position in board
}

get_board_labels

Retrieve all labels from a Trello board.

// Parameters
{
  "boardId": "string" // Trello board ID
}

create_label

Create a new label on a Trello board.

// Parameters
{
  "name": "string",         // Required: Label name
  "idBoard": "string",      // Required: Trello board ID
  "color": "yellow|purple|blue|red|green|orange|black|sky|pink|lime?" // Optional: Label color
}

get_card_checklists

Get all checklists (with their items) on a Trello card.

// Parameters
{
  "cardId": "string"        // Required: Trello card ID
}

create_checklist

Create a checklist on a card. Optionally seed it with initial items in one call.

// Parameters
{
  "idCard": "string",                  // Required: Card ID to attach the checklist to
  "name": "string",                    // Required: Checklist name
  "pos": "number|'top'|'bottom'?",     // Optional: Position on the card
  "items": "string[]?"                 // Optional: Initial items (created in order, unchecked)
}

add_checklist_item

Add an item to an existing checklist.

// Parameters
{
  "idChecklist": "string",             // Required: Checklist ID
  "name": "string",                    // Required: Item text
  "pos": "number|'top'|'bottom'?",     // Optional: Position within the checklist
  "checked": "boolean?"                // Optional: Initial checked state (default false)
}

update_checklist_item

Update a checklist item — rename, mark complete/incomplete, or reorder.

// Parameters
{
  "idCard": "string",                  // Required: Card ID containing the checklist
  "idCheckItem": "string",             // Required: Checklist item ID
  "name": "string?",                   // Optional: New text
  "state": "'complete'|'incomplete'?", // Optional: Completion state
  "pos": "number|'top'|'bottom'?"      // Optional: New position
}

delete_checklist

Delete a checklist (and all its items) from a card.

// Parameters
{
  "idChecklist": "string"   // Required: Checklist ID
}

attach_card_link

Attach a URL to a card. When the URL points to another Trello card (https://trello.com/c/<shortLink>), Trello renders it as a card-preview chip in the sidebar — useful for cross-linking related cards.

// Parameters
{
  "idCard": "string",   // Required: Card to attach the link to
  "url": "string",      // Required: URL (use a Trello card URL for cross-links)
  "name": "string?"     // Optional: display name for the attachment
}

attach_card_file

Upload a local file from disk as an attachment on a card (images, PDFs, logs, etc.). To attach a URL instead, use attach_card_link.

// Parameters
{
  "idCard": "string",     // Required: Card to attach the file to
  "filePath": "string",   // Required: Absolute path to the local file to upload
  "name": "string?",      // Optional: display name (defaults to the file's name)
  "mimeType": "string?"   // Optional: MIME type (e.g. "image/png"); inferred when omitted
}

get_card_attachments

Get all attachments on a card.

// Parameters
{
  "cardId": "string"   // Required: Card ID
}

Example Workflows

Card Creation

Create a new card in list 507f191e810c19729de860ea titled "Implement new feature" with description "Add authentication system" assigned to member 5a2e4b6c8d9e1f2a3b4c5d6e and due date 2024-12-31

Card Updates

Update card abc123 to change title to "Authentication Complete", mark due date as complete, and move to list 507f191e810c19729de860eb

Project Analysis

Analyze all cards in board 507f1f77bcf86cd799439011 and summarize project status

Task Management

Find all overdue cards across my boards and add status update comments

Team Collaboration

Get comments from card abc123 and suggest next steps based on the discussion

Automated Workflows

Create a card for each action item from meeting notes, assign to relevant team members, and set due dates

List Management

Create a new list on board 507f1f77bcf86cd799439011 named "In Review" positioned at the top

Label Organization

Get all labels from board 507f1f77bcf86cd799439011 and create a new "High Priority" label with red color

Development

Local Development

# Clone and setup
git clone [email protected]:wachterjohannes/trello-mcp.git
cd trello-mcp
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your Trello credentials

# Build and run
npm run build
npm start

Available Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Development mode with watch
• npm start - Run the compiled server
• npm run trello - Run the CLI (e.g. npm run trello -- list)
• npm test - Build and run the test suite
• npm run lint - Run ESLint

Project Architecture

src/
├── tools.ts           # Tool registry shared by the MCP server and the CLI
├── index.ts           # MCP server (stdio); delegates to the CLI when given arguments
├── cli.ts             # Command line interface: parsing, help, output
├── script.ts          # JSON script runner with step chaining
├── setup.ts           # `trello setup`: authentication + skill installation
├── config.ts          # Stored credentials and token verification
├── skills.ts          # Agent-root detection and skill installation
├── install-skills.ts  # postinstall entry point (global installs only)
└── trello-client.ts   # Trello API client with TypeScript interfaces
skills/trello-cli/     # Bundled agent skill, installed into agent roots

Adding a tool means adding one entry to src/tools.ts — it then appears in the MCP server, trello list, the CLI help and the script runner at once.

Security

• API credentials are never logged or exposed
• Environment-based authentication prevents credential leakage
• Comprehensive input validation on all tool parameters
• Secure handling of Trello API responses

Troubleshooting

Common Issues

Authentication Errors

Error: TRELLO_API_KEY and TRELLO_TOKEN environment variables are required

→ Ensure your API credentials are properly set in environment variables

Invalid Board/Card IDs

Error: Failed to get board cards: Request failed with status code 400

→ Verify the board or card ID exists and you have access permissions

Rate Limiting

Error: Request failed with status code 429

→ Trello API rate limits apply; implement retry logic or reduce request frequency

Publishing

This package is published to npm as @asapo/trello-mcp-server. To publish updates:

npm version patch|minor|major
npm publish

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

MIT License - see LICENSE file for details.