API Reference - kocakli/Trello-Desktop-MCP GitHub Wiki

API Reference

This document provides comprehensive technical API documentation for Trello Desktop MCP.

API Overview

Trello Desktop MCP implements the Model Context Protocol (MCP) to provide standardized tool discovery and execution. All communication follows MCP specification 2024-11-05.

Protocol Structure

// MCP Request Structure
interface MCPRequest {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params: object;
}

// MCP Response Structure
interface MCPResponse {
  jsonrpc: "2.0";
  id: string | number;
  result?: object;
  error?: MCPError;
}

Tool Categories

Essential Tools (Phase 1)

trello_search

Universal search across all Trello content

interface SearchRequest {
  query: string;                          // Search term (required)
  modelTypes?: string[];                  // Filter by content type
  boardIds?: string[];                    // Limit to specific boards
  boardsLimit?: number;                   // Max board results (default: 10)
  cardsLimit?: number;                    // Max card results (default: 50)
  membersLimit?: number;                  // Max member results (default: 25)
}

interface SearchResponse {
  boards: TrelloBoard[];
  cards: TrelloCard[];
  members: TrelloMember[];
  organizations: TrelloOrganization[];
}

Example Usage:

{
  "name": "trello_search",
  "arguments": {
    "query": "authentication bug",
    "modelTypes": ["cards", "boards"],
    "cardsLimit": 20
  }
}

trello_get_user_boards

Get all boards accessible to the current user

interface GetUserBoardsRequest {
  filter?: "all" | "open" | "closed";     // Board status filter (default: "open")
}

interface GetUserBoardsResponse {
  boards: TrelloBoard[];
  summary: {
    totalBoards: number;
    openBoards: number;
    closedBoards: number;
  };
}

get_board_details

Get comprehensive board information

interface GetBoardDetailsRequest {
  boardId: string;                        // 24-character board ID (required)
  includeLists?: boolean;                 // Include board lists (default: false)
  includeCards?: boolean;                 // Include all cards (default: false)
}

interface GetBoardDetailsResponse {
  board: TrelloBoard;
  lists?: TrelloList[];
  cards?: TrelloCard[];
  summary: BoardSummary;
}

get_card

Get comprehensive card details

interface GetCardRequest {
  cardId: string;                         // 24-character card ID (required)
  includeMembers?: boolean;               // Include assigned members
  includeLabels?: boolean;                // Include card labels
  includeChecklists?: boolean;            // Include checklists
}

interface GetCardResponse {
  card: TrelloCard;
  members?: TrelloMember[];
  labels?: TrelloLabel[];
  checklists?: TrelloChecklist[];
}

create_card

Create new cards with full metadata

interface CreateCardRequest {
  name: string;                           // Card title (1-16384 chars, required)
  idList: string;                         // Target list ID (required)
  desc?: string;                          // Card description
  pos?: string | number;                  // Position: "top", "bottom", or number
  due?: string;                           // Due date (ISO 8601 format)
  idMembers?: string[];                   // Member IDs to assign
  idLabels?: string[];                    // Label IDs to apply
}

interface CreateCardResponse {
  card: TrelloCard;
  summary: string;
}

Board Management Tools

list_boards (Legacy)

Simple board listing for compatibility

interface ListBoardsRequest {
  filter?: "all" | "open" | "closed";
}

interface ListBoardsResponse {
  boards: TrelloBoard[];
}

get_lists

Get all lists in a board

interface GetListsRequest {
  boardId: string;                        // Board ID (required)
  filter?: "all" | "open" | "closed";    // List status filter
}

interface GetListsResponse {
  lists: TrelloList[];
  summary: {
    totalLists: number;
    openLists: number;
    closedLists: number;
  };
}

trello_create_list

Create new lists on boards

interface CreateListRequest {
  name: string;                           // List name (required)
  idBoard: string;                        // Target board ID (required)
  pos?: string | number;                  // Position: "top", "bottom", or number
}

interface CreateListResponse {
  list: TrelloList;
  summary: string;
}

Card Operations Tools

update_card

Update existing card properties

interface UpdateCardRequest {
  cardId: string;                         // Card ID (required)
  name?: string;                          // New card title
  desc?: string;                          // New description
  due?: string | null;                    // New due date or null to remove
  closed?: boolean;                       // Archive/unarchive card
  idMembers?: string[];                   // Update member assignments
  idLabels?: string[];                    // Update label assignments
}

interface UpdateCardResponse {
  card: TrelloCard;
  changes: string[];                      // List of changes made
}

move_card

Move cards between lists

interface MoveCardRequest {
  cardId: string;                         // Card ID (required)
  idList: string;                         // Target list ID (required)
  pos?: string | number;                  // Position in target list
}

interface MoveCardResponse {
  card: TrelloCard;
  summary: string;
}

trello_add_comment

Add comments to cards

interface AddCommentRequest {
  cardId: string;                         // Card ID (required)
  text: string;                           // Comment text (required)
}

interface AddCommentResponse {
  comment: TrelloAction;
  summary: string;
}

trello_get_list_cards

Get all cards from a specific list

interface GetListCardsRequest {
  listId: string;                         // List ID (required)
  filter?: "all" | "open" | "closed";    // Card status filter
  includeMembers?: boolean;               // Include member data
  includeLabels?: boolean;                // Include label data
}

interface GetListCardsResponse {
  cards: TrelloCard[];
  summary: {
    totalCards: number;
    openCards: number;
    closedCards: number;
  };
}

Collaboration Tools

trello_get_member

Get member information

interface GetMemberRequest {
  memberId: string;                       // Member ID or username (required)
  includeBoards?: boolean;                // Include member's boards
  includeOrganizations?: boolean;         // Include organizations
}

interface GetMemberResponse {
  member: TrelloMember;
  boards?: TrelloBoard[];
  organizations?: TrelloOrganization[];
}

trello_get_board_members

Get all board members

interface GetBoardMembersRequest {
  boardId: string;                        // Board ID (required)
}

interface GetBoardMembersResponse {
  members: TrelloMember[];
  summary: {
    totalMembers: number;
    adminMembers: number;
    normalMembers: number;
  };
}

trello_get_board_labels

Get board labels

interface GetBoardLabelsRequest {
  boardId: string;                        // Board ID (required)
}

interface GetBoardLabelsResponse {
  labels: TrelloLabel[];
  summary: {
    totalLabels: number;
    usedLabels: number;
  };
}

Advanced Features Tools

trello_get_board_cards

Get all cards from a board

interface GetBoardCardsRequest {
  boardId: string;                        // Board ID (required)
  includeAttachments?: boolean;           // Include attachments
  includeMembers?: boolean;               // Include member data
  filter?: string;                        // Card filter (default: "open")
}

interface GetBoardCardsResponse {
  cards: TrelloCard[];
  summary: BoardCardsSummary;
}

trello_get_card_actions

Get card activity history

interface GetCardActionsRequest {
  cardId: string;                         // Card ID (required)
  filter?: string;                        // Action type filter
  limit?: number;                         // Max results (default: 50)
}

interface GetCardActionsResponse {
  actions: TrelloAction[];
  summary: {
    totalActions: number;
    actionTypes: Record<string, number>;
  };
}

trello_get_card_attachments

Get card attachments

interface GetCardAttachmentsRequest {
  cardId: string;                         // Card ID (required)
  fields?: string[];                      // Specific fields to return
}

interface GetCardAttachmentsResponse {
  attachments: TrelloAttachment[];
  summary: {
    totalAttachments: number;
    totalSize: number;
  };
}

trello_get_card_checklists

Get card checklists

interface GetCardChecklistsRequest {
  cardId: string;                         // Card ID (required)
  includeCheckItems?: boolean;            // Include checklist items
  fields?: string[];                      // Specific fields to return
}

interface GetCardChecklistsResponse {
  checklists: TrelloChecklist[];
  summary: ChecklistSummary;
}

Data Types

Core Entities

TrelloBoard

interface TrelloBoard {
  id: string;                             // 24-character board ID
  name: string;                           // Board name
  desc: string;                           // Board description
  url: string;                            // Board URL
  closed: boolean;                        // Archive status
  starred: boolean;                       // Starred by user
  dateLastActivity: string;               // Last activity timestamp
  dateLastView: string;                   // Last viewed timestamp
  idOrganization?: string;                // Organization ID
  lists?: TrelloList[];                   // Board lists (if requested)
  cards?: TrelloCard[];                   // Board cards (if requested)
  members?: TrelloMember[];               // Board members (if requested)
  labels?: TrelloLabel[];                 // Board labels (if requested)
}

TrelloCard

interface TrelloCard {
  id: string;                             // 24-character card ID
  name: string;                           // Card title
  desc: string;                           // Card description
  url: string;                            // Card URL
  closed: boolean;                        // Archive status
  pos: number;                            // Position in list
  due?: string;                           // Due date (ISO format)
  dueComplete: boolean;                   // Due date completion status
  dateLastActivity: string;               // Last activity timestamp
  idBoard: string;                        // Parent board ID
  idList: string;                         // Parent list ID
  idMembers: string[];                    // Assigned member IDs
  labels: TrelloLabel[];                  // Applied labels
  badges: TrelloBadges;                   // Card statistics
  members?: TrelloMember[];               // Assigned members (if requested)
  checklists?: TrelloChecklist[];         // Card checklists (if requested)
  attachments?: TrelloAttachment[];       // Card attachments (if requested)
}

TrelloList

interface TrelloList {
  id: string;                             // 24-character list ID
  name: string;                           // List name
  closed: boolean;                        // Archive status
  pos: number;                            // Position on board
  idBoard: string;                        // Parent board ID
  cards?: TrelloCard[];                   // List cards (if requested)
}

TrelloMember

interface TrelloMember {
  id: string;                             // 24-character member ID
  username: string;                       // Member username
  fullName: string;                       // Display name
  email?: string;                         // Email address
  avatarHash?: string;                    // Avatar hash for URL construction
  url: string;                            // Member profile URL
  memberType: "admin" | "normal" | "observer"; // Board membership type
  boards?: TrelloBoard[];                 // Member's boards (if requested)
  organizations?: TrelloOrganization[];   // Member's organizations (if requested)
}

TrelloLabel

interface TrelloLabel {
  id: string;                             // 24-character label ID
  name: string;                           // Label name
  color: string;                          // Label color
  idBoard: string;                        // Parent board ID
  uses: number;                           // Usage count
}

Metadata Types

TrelloBadges

interface TrelloBadges {
  votes: number;                          // Vote count
  viewingMemberVoted: boolean;            // Current user voted
  subscribed: boolean;                    // Subscription status
  fogbugz: string;                        // FogBugz integration
  checkItems: number;                     // Total checklist items
  checkItemsChecked: number;              // Completed checklist items
  comments: number;                       // Comment count
  attachments: number;                    // Attachment count
  description: boolean;                   // Has description
  due?: string;                           // Due date
  dueComplete: boolean;                   // Due date completed
}

TrelloChecklist

interface TrelloChecklist {
  id: string;                             // 24-character checklist ID
  name: string;                           // Checklist name
  idBoard: string;                        // Parent board ID
  idCard: string;                         // Parent card ID
  pos: number;                            // Position on card
  checkItems: TrelloCheckItem[];          // Checklist items
}

interface TrelloCheckItem {
  id: string;                             // 24-character item ID
  name: string;                           // Item text
  state: "complete" | "incomplete";      // Completion status
  pos: number;                            // Position in checklist
  due?: string;                           // Due date
  idMember?: string;                      // Assigned member
}

TrelloAttachment

interface TrelloAttachment {
  id: string;                             // 24-character attachment ID
  name: string;                           // Attachment name
  url: string;                            // Attachment URL
  bytes?: number;                         // File size in bytes
  date: string;                           // Upload timestamp
  mimeType?: string;                      // MIME type
  previews?: TrelloAttachmentPreview[];   // Preview images
}

TrelloAction

interface TrelloAction {
  id: string;                             // 24-character action ID
  type: string;                           // Action type
  date: string;                           // Action timestamp
  data: object;                           // Action-specific data
  memberCreator: TrelloMember;            // Action performer
  card?: TrelloCard;                      // Related card (if applicable)
  board?: TrelloBoard;                    // Related board (if applicable)
  list?: TrelloList;                      // Related list (if applicable)
}

Error Handling

Error Response Structure

interface MCPError {
  code: number;                           // Error code
  message: string;                        // Error message
  data?: object;                          // Additional error data
}

interface TrelloError {
  message: string;                        // User-friendly error message
  error: string;                          // Technical error details
  status?: number;                        // HTTP status code
  code: string;                           // Error category code
}

Error Codes

Code Category Description
INVALID_CREDENTIALS Authentication API key or token invalid
INSUFFICIENT_PERMISSIONS Authorization Token lacks required permissions
NOT_FOUND Resource Requested resource doesn't exist
RATE_LIMIT_EXCEEDED Rate Limiting API rate limit exceeded
VALIDATION_ERROR Input Invalid input parameters
NETWORK_ERROR Network Network connectivity issues
TIMEOUT_ERROR Network Request timeout
SERVER_ERROR Server Trello API server error
UNKNOWN_ERROR General Unexpected error occurred

Error Examples

// Invalid credentials
{
  "error": {
    "code": -32000,
    "message": "Invalid or expired Trello credentials. Please update your API key and token in Claude Desktop settings.",
    "data": {
      "code": "INVALID_CREDENTIALS",
      "status": 401
    }
  }
}

// Resource not found
{
  "error": {
    "code": -32000,
    "message": "Board not found. It may have been deleted or you may not have access.",
    "data": {
      "code": "NOT_FOUND",
      "status": 404
    }
  }
}

// Rate limit exceeded
{
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded. Please wait before making additional requests.",
    "data": {
      "code": "RATE_LIMIT_EXCEEDED",
      "status": 429,
      "retryAfter": 10
    }
  }
}

Rate Limiting

Trello API Limits

  • Request Limit: 300 requests per 10 seconds per API key
  • Reset Interval: Every 10 seconds
  • Burst Capacity: Up to 300 requests immediately

Rate Limit Headers

interface RateLimitInfo {
  limit: number;                          // Total requests allowed
  remaining: number;                      // Requests remaining
  resetTime: number;                      // Reset timestamp (Unix)
}

Rate Limit Handling

The MCP server automatically handles rate limiting:

  1. Detection: Monitors rate limit headers in API responses
  2. Retry Logic: Implements exponential backoff for retry attempts
  3. Automatic Recovery: Waits for rate limit reset before retrying
  4. Client Notification: Provides clear error messages for rate limit issues

Authentication

Credential Requirements

interface TrelloCredentials {
  apiKey: string;                         // 32-character API key
  token: string;                          // 64+ character token
}

Token Permissions

Required token permissions:

  • Read: Access to view boards, cards, lists, members
  • Write: Ability to create, update, and delete content
  • Account: Access to user profile information

Credential Validation

# Test credentials
curl "https://api.trello.com/1/members/me?key=API_KEY&token=TOKEN"

# Expected response: User profile with boards and organizations

Response Formats

Standard Response Structure

interface ToolResponse {
  content: ContentBlock[];
}

interface ContentBlock {
  type: "text" | "image" | "resource";
  text?: string;
  data?: string;
  mimeType?: string;
}

Text Response Format

{
  "content": [
    {
      "type": "text",
      "text": "## Board: Project Management\n\n**Lists:**\n- To Do (5 cards)\n- In Progress (3 cards)\n- Done (12 cards)\n\n**Summary:** 20 total cards, 8 active cards"
    }
  ]
}

Rich Response Format

{
  "content": [
    {
      "type": "text", 
      "text": "Card created successfully!"
    },
    {
      "type": "resource",
      "resource": {
        "uri": "trello://card/card_id",
        "name": "New Task Card",
        "description": "Task created in To Do list"
      }
    }
  ]
}

SDK Usage Examples

Basic Tool Call

// MCP client calling a tool
const response = await client.callTool({
  name: "trello_get_user_boards",
  arguments: {
    filter: "open"
  }
});

Error Handling

try {
  const response = await client.callTool({
    name: "get_board_details",
    arguments: {
      boardId: "invalid_id"
    }
  });
} catch (error) {
  if (error.code === "NOT_FOUND") {
    console.log("Board not found");
  } else if (error.code === "INVALID_CREDENTIALS") {
    console.log("Please check your API credentials");
  }
}

Batch Operations

// Multiple related operations
const boardResponse = await client.callTool({
  name: "get_board_details",
  arguments: { boardId: "board_id", includeLists: true }
});

const cardResponse = await client.callTool({
  name: "create_card",
  arguments: {
    name: "New Task",
    idList: boardResponse.result.lists[0].id
  }
});

Next: Review Tool Development for creating custom tools or Testing for testing strategies.