MCP Trello Integration Suite

A Model Context Protocol (MCP) server implementation providing advanced tooling for interacting with the Atlassian Trello platform. This module ensures fluid integration with the Trello API infrastructure, automatically handling request rate constraints, maintaining data type integrity, and processing operational failures gracefully.

🎉 Performance Upgrade v1.5.0: Now Utilizing Bun! ⚡

This utility has been fully migrated to the Bun runtime environment! 🚀 This transition yields a significant performance uplift, measured between 2.8x and 4.4x faster execution. All conventional execution methods (npx, pnpx, and npm) will maintain full backward compatibility.

✨ Release Highlights:

• 🚀 Accelerated Execution: Experience a snappier, high-throughput server performance.
• BUN Bun Foundation: The core runtime has been swapped to the high-speed Bun JavaScript engine.
• 📖 Extensive Documentation: A newly added examples directory furnishes detailed operational blueprints across JavaScript, Python, and TypeScript environments.

Additionally: Modernized MCP Software Development Kit architecture, heightened type assertion safety, and comprehensive reference guides!

Revision History

For a granular breakdown of modifications, consult the primary CHANGELOG.md document.

Core Capabilities

• Full Board Interoperability: Comprehensive manipulation of Trello artifacts: boards, lists, and temporal activities.
• 🆕 Exhaustive Card Data Retrieval: Obtain every facet of card information, encompassing subtasks (checklists), attached media, categorization labels, assigned team members, and discussion threads.
• Media Upload Utility: Facilitate the attachment of any supported file format (PDFs, documentation, video assets, imagery, etc.) sourced from accessible URLs.
• Integrated Traffic Control: Strictly adheres to Trello API quotas (300 calls/10s per key, 100 calls/10s per token).
• Type-Secure Engineering: Architected entirely in TypeScript, furnishing comprehensive interface definitions.
• Input Integrity Checks: Rigorous validation applied to every incoming API argument.
• Failure Management: Implements graceful error mitigation yielding clear, actionable diagnostic messages.
• Context Switching: Permits dynamic modification of active boards and organizational workspaces without necessitating service restarts.
• Markdown Export: Capability to serialize detailed card data into easily digestible Markdown format.

Deployment Instructions

🚀 MCP Registry Installation (Preferred Method)

The Trello MCP Server is now cataloged in the official MCP Registry! MCP-compatible consumers can automatically locate and provision this server.

For registry-aware clients:

1. Query for "mcp-server-trello" or the unique identifier "io.github.delorenj/mcp-server-trello".
2. Initiate direct installation from the registry repository.
3. Supply the necessary Trello authentication credentials.

🚀 Rapid Initialization via Bun (Fastest Path)

If Bun is present on your system, utilizing bunx offers the most expedient server startup sequence:

{   "mcpServers": {     "trello": {       "command": "bunx",       "args": ["@delorenj/mcp-server-trello"],       "env": {         "TRELLO_API_KEY": "your-api-key",         "TRELLO_TOKEN": "your-token"       }     }   } }

Quick Start with npx / pnpx / bunx

npx or pnpx remain viable execution routes. These methods preclude a global installation requirement, although bunx (as shown above) offers superior speed.

{   "mcpServers": {     "trello": {       "command": "bunx",       "args": ["@delorenj/mcp-server-trello"],       "env": {         "TRELLO_API_KEY": "your-api-key",         "TRELLO_TOKEN": "your-token"       }     }   } }

Alternatively, if employing mise, execution can be explicitly invoked via mise exec:

{   "mcpServers": {     "trello": {       "command": "mise",       "args": ["x", "--", "bunx", "@delorenj/mcp-server-trello"],       "env": {         "TRELLO_API_KEY": "your-api-key",         "TRELLO_TOKEN": "your-token"       }     }   } }

To establish a connection to a Trello organization, you must manually obtain a TRELLO_TOKEN for that context. Following the setup of your Trello Power-Up, navigate to this authorization endpoint:

https://trello.com/1/authorize?expiration=never&name=YOUR_APP_NAME&scope=read,write&response_type=token&key=YOUR_API_KEY

Substitute the placeholders:

• YOUR_APP_NAME: Insert a unique designation for your application (e.g., "My Integration Client"). This label is presented during Trello user consent.
• YOUR_API_KEY: Use the Trello Power-Up API Key.

This action generates the necessary token for platform integration.

[!CAUTION] The use of expiration=never provisions a persistent, non-expiring token. For heightened security postures, utilize expiration=30days and implement a scheduled renewal process if operational constraints permit.

Prerequisites: Obtaining Bun

The most streamlined method for acquiring the bun runtime (and consequently bunx) is via mise:

bash

Install mise (if necessary)

curl https://mise.run | sh

Set the latest Bun version as the system default

mise use bun@latest -g

Alternatively, execute mise install within the project directory for local provisioning

cd /path/to/mcp-server-trello mise install

NPM Installation Path

If a direct npm invocation is preferred:

bash npm install -g @delorenj/mcp-server-trello

(A faster equivalent is bun add -g @delorenj/mcp-server-trello)

Subsequently, deploy npx mcp-server-trello as the execution command within your MCP configuration object.

Smithery Deployment

To provision the Trello Server automatically for Claude Desktop via Smithery:

bash

Using bunx (Recommended)

bunx -y @smithery/cli install @delorenj/mcp-server-trello --client claude

Using npx

npx -y @smithery/cli install @delorenj/mcp-server-trello --client claude

Containerized Deployment (Docker)

For execution within container orchestration environments:

1. Clone the source repository:

bash git clone https://github.com/delorenj/mcp-server-trello cd mcp-server-trello

1. Duplicate the environment definition template and populate credential values:

bash cp .env.template .env

1. Assemble and initiate the service using Docker Compose:

bash docker compose up --build

Operational Configuration

Runtime Environment Parameters

The server's behavior is governed by environment variables, typically defined in a .env file in the root directory:

env

Mandatory: Trello API Access Credentials

TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token

Optional (Legacy): Initial default board ID (can be superseded via set_active_board)

TRELLO_BOARD_ID=your-board-id

Optional: Initial organizational workspace ID (can be superseded via set_active_workspace)

TRELLO_WORKSPACE_ID=your-workspace-id

You can procure these values from:

• API Key: https://trello.com/app-key
• Token: Generated using the API Key.
• Board ID (optional/legacy): Extractable from the board URL path.
• Workspace ID: Obtainable via list_workspaces tool output or workspace administration screens.

Contextual Board and Workspace Administration

Since revision 0.3.0, the MCP server embraces flexible context management:

1. Multi-Board Capability: All operational methods now optionally accept a boardId argument.    - Omit setting TRELLO_BOARD_ID in environment variables and supply boardId directly in the API invocation payload.    - Use TRELLO_BOARD_ID for the standard context, with the option to override it via the method parameter.

2. Persistent Context Switching: Utilize organizational toolsets for dynamic context setting.    - The value set in TRELLO_BOARD_ID defines the initial operational context.    - The active board can be instantaneously modified using the set_active_board utility.    - The chosen context persists across server restarts (persisted in ~/.trello-mcp/config.json).    - A similar mechanism exists for establishing and maintaining a default active workspace using set_active_workspace.

This architecture enables seamless workflow execution across numerous boards and organizations without service interruption.

Illustrative Operational Sequence

1. Begin by enumerating accessible boards:

typescript {   name: 'list_boards',   arguments: {} }

1. Designate the desired board as active:

typescript {   name: 'set_active_board',   arguments: {     boardId: "abc123"  // ID obtained from the preceding list_boards call   } }

1. List organizational contexts if required:

typescript {   name: 'list_workspaces',   arguments: {} }

1. Establish the active workspace if necessary:

typescript {   name: 'set_active_workspace',   arguments: {     workspaceId: "xyz789"  // ID retrieved from list_workspaces output   } }

1. Verify the parameters of the currently active board context:

typescript {   name: 'get_active_board_info',   arguments: {} }

Date Formatting Protocol

When providing temporal values to the Trello MCP server, adhere strictly to these formatting specifications:

• Due Date (dueDate): Mandates the complete ISO 8601 specification including time component (e.g., 2023-12-31T12:00:00Z).
• Start Date (start): Accepts only the date component in YYYY-MM-DD format (e.g., 2025-08-05).

This differentiation mirrors Trello's API expectations, where start markers are date-centric, while due dates accommodate precise temporal assignment.

Available Modalities (Tools)

Subtask/Checklist Manipulation Tools 🆕

get_checklist_items

Retrieves all constituent items belonging to a checklist identified by its title.

typescript {   name: 'get_checklist_items',   arguments: {     name: string,        // Label/Name of the checklist whose elements are to be fetched     boardId?: string     // Optional: Target board identifier (defaults to active context)   } }

add_checklist_item

Inserts a new actionable entry into an extant checklist.

typescript {   name: 'add_checklist_item',   arguments: {     text: string,          // Content/Label for the new checklist element     checkListName: string,  // Precise title of the parent checklist     boardId?: string      // Optional: Target board identifier (defaults to active context)   } }

find_checklist_items_by_description

Scans all checklist elements within a board to locate those whose description text contains a specified substring.

typescript {   name: 'find_checklist_items_by_description',   arguments: {     description: string,  // Substring to search for within checklist item narratives     boardId?: string      // Optional: Target board identifier (defaults to active context)   } }

get_acceptance_criteria

Specifically retrieves the contents of the checklist named "Acceptance Criteria".

typescript {   name: 'get_acceptance_criteria',   arguments: {     boardId?: string  // Optional: Target board identifier (defaults to active context)   } }

get_checklist_by_name

Retrieves the full structure of a specified checklist, including item statuses and overall completion metric.

typescript {   name: 'get_checklist_by_name',   arguments: {     name: string,     // Exact name of the checklist object     boardId?: string  // Optional: Target board identifier (defaults to active context)   } }

Returns: A structured CheckList payload containing:

• id: Unique identifier for the checklist
• name: Checklist title
• items: Array detailing each CheckListItem object
• percentComplete: Percentage completion metric (0 to 100)

get_card

Fetches exhaustive metadata for a singular Trello card, striving for feature parity with human-observed card detail.

typescript {   name: 'get_card',   arguments: {     cardId: string,        // Short ID (e.g., 'FdhbArbK') or full unique identifier of the Trello card     includeMarkdown?: boolean // If true, outputs formatted markdown representation; otherwise, returns raw JSON (default: false)   } }

Returns: Complete card data structure, incorporating:

• ✅ Subtask status and ownership mapping
• 📎 Attached resources with thumbnail previews and attributes
• 🏷️ Categorization labels with associated color codes
• 👥 User assignments
• 💬 Chronology of comments and system events
• 📊 Summary statistics (badges)
• 🎨 Featured cover image data
• 📍 Association details for the parent board and list

get_cards_by_list_id

Queries and retrieves all active cards residing within a list identified by its ID.

typescript {   name: 'get_cards_by_list_id',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     listId: string    // Unique identifier for the target Trello list   } }

get_lists

Retrieves the complete set of organizational lists associated with a specified board.

typescript {   name: 'get_lists',   arguments: {     boardId?: string  // Optional: Board context selector (defaults to active context)   } }

get_recent_activity

Retrieves the most recent chronological events logged against a board.

typescript {   name: 'get_recent_activity',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     limit?: number    // Optional: Maximum count of activities to return (default: 10)   } }

add_card_to_list

Creates a new card entity and places it within a designated list.

typescript {   name: 'add_card_to_list',   arguments: {     boardId?: string,     // Optional: Board context selector (defaults to active context)     listId: string,       // ID of the destination list     name: string,         // Title for the new card     description?: string, // Optional: Detailed body content for the card     dueDate?: string,     // Optional: Target completion date (ISO 8601 with time)     start?: string,       // Optional: Assignment start date (YYYY-MM-DD, date only)     labels?: string[]     // Optional: Array of label identifiers to apply   } }

update_card_details

Modifies existing attributes of a specified card record.

typescript {   name: 'update_card_details',   arguments: {     boardId?: string,     // Optional: Board context selector (defaults to active context)     cardId: string,       // Unique identifier for the card being modified     name?: string,        // Optional: Revised card title     description?: string, // Optional: Revised card body content     dueDate?: string,     // Optional: New deadline (ISO 8601 with time)     start?: string,       // Optional: New commencement date (YYYY-MM-DD, date only)     dueComplete?: boolean,// Optional: Flag to mark the due date as fulfilled (true/false)     labels?: string[]     // Optional: Replacement set of label IDs   } }

archive_card

Transitions a specified card to the archived state (soft delete).

typescript {   name: 'archive_card',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     cardId: string    // Target card identifier   } }

add_list_to_board

Provisions a new organizational list structure onto a target board.

typescript {   name: 'add_list_to_board',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     name: string      // Title for the newly created list   } }

archive_list

Transitions a specified list structure to the archived state.

typescript {   name: 'archive_list',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     listId: string    // Target list identifier   } }

get_my_cards

Retrieves a consolidated view of all cards currently assigned to the authenticated user across accessible boards.

typescript {   name: 'get_my_cards',   arguments: {} }

move_card

Translocates a card from its current list to a different list, optionally across board boundaries.

typescript {   name: 'move_card',   arguments: {     boardId?: string,  // Optional: ID of the destination board (uses default if omitted)     cardId: string,    // Identifier of the card entity to relocate     listId: string     // Identifier for the destination list   } }

attach_image_to_card

Embeds an image resource, sourced directly from a URL, onto a specified card.

typescript {   name: 'attach_image_to_card',   arguments: {     boardId?: string, // Optional: Board context selector (defaults to active context)     cardId: string,   // Target card identifier     imageUrl: string, // Absolute URL pointing to the image resource     name?: string     // Optional: Descriptive filename for the attachment (defaults to standard identifier)   } }

attach_file_to_card

Links any arbitrary file type to a card, using either a web URL or a local file path accessible via the file:// protocol (e.g., file:///path/to/document.pdf).

typescript {   name: 'attach_file_to_card',   arguments: {     boardId?: string,  // Optional: Board context selector (defaults to active context)     cardId: string,   // Target card identifier     fileUrl: string,   // URL or local path specifying the file resource     name?: string,     // Optional: Desired name for the attachment (defaults to filename for local paths)     mimeType?: string  // Optional: Standardized MIME type (e.g., "application/pdf", "text/plain")   } }

list_boards

Enumerates all Trello boards accessible by the authenticated user credentials.

typescript {   name: 'list_boards',   arguments: {} }

set_active_board

Establishes a new default board context for subsequent operations that do not explicitly define a boardId.

typescript {   name: 'set_active_board',   arguments: {     boardId: string  // Identifier of the board to set as the default context   } }

list_workspaces

Enumerates all organizational workspaces the authenticated user belongs to.

typescript {   name: 'list_workspaces',   arguments: {} }

set_active_workspace

Sets a default organizational workspace context for operations that benefit from it.

typescript {   name: 'set_active_workspace',   arguments: {     workspaceId: string  // Identifier of the workspace to set as the default context   } }

list_boards_in_workspace

Retrieves a catalogue of all boards associated with a specific organizational unit.

typescript {   name: 'list_boards_in_workspace',   arguments: {     workspaceId: string  // Identifier of the parent workspace   } }

get_active_board_info

Returns detailed metadata about the board currently designated as the active context.

typescript {   name: 'get_active_board_info',   arguments: {} }

Integration Blueprints

🎨 Synergy with Ideogram MCP Server

This Trello server integrates seamlessly with the visual generation capabilities of the @flowluap/ideogram-mcp-server. Generate visual assets via Ideogram and immediately affix them to relevant Trello tasks!

Coordinated Execution Flow

1. Image Synthesis via Ideogram:

typescript // Invoking ideogram-mcp-server {   name: 'generate_image',   arguments: {     prompt: "A futuristic dashboard design with neon accents",     aspect_ratio: "16:9"   } } // Expected Output: { image_url: "https://..." }

1. Attachment to Trello Card:

typescript // Invoking trello-mcp-server {   name: 'attach_image_to_card',   arguments: {     cardId: "your-card-id",     imageUrl: "https://...", // URL returned from the Ideogram service     name: "Dashboard Mockup v1"   } }

Combined Server Configuration

Configure both services within your Claude Desktop environment definition. Employ bunx for optimal initialization speed.

{   "mcpServers": {     "trello": {       "command": "bunx",       "args": ["@delorenj/mcp-server-trello"],       "env": {         "TRELLO_API_KEY": "your-trello-api-key",         "TRELLO_TOKEN": "your-trello-token"       }     },     "ideogram": {       "command": "bunx",       "args": ["@flowluap/ideogram-mcp-server"],       "env": {         "IDEOGRAM_API_KEY": "your-ideogram-api-key"       }     }   } }

This setup facilitates fluid generation of visual assets and their subsequent organization within the Trello task management system, all managed via Claude.

API Rate Governance

The server employs a sophisticated token bucket mechanism to ensure strict adherence to Trello's documented request velocity ceilings:

• 300 API interactions per 10-second window per API Key.
• 100 API interactions per 10-second window per access Token.

Rate management is automated; any excess requests are automatically placed into a queue to await permissible execution times.

Operational Diagnostics

The server furnishes precise error reporting across several common failure modalities:

• Malformed or invalid argument submission
• Exceeded rate limiting thresholds
• Authentication credential failures
• Underlying network connectivity faults
• Non-existent or invalid board/list/card references

Development Lifecycle

Necessary Prerequisites

• Bun runtime environment (Version 1.0.0 or newer is required)

Initial Setup Procedure

1. Clone the repository source code

bash git clone https://github.com/delorenj/mcp-server-trello cd mcp-server-trello

1. Install requisite project dependencies

bash bun install

1. Compile the source assets

bash bun run build

Executing Verification Suites

To execute the integrated test suite, utilize the following command:

bash bun test

Running Evaluation Scripts (Evals)

The evaluation package utilizes an integrated MCP client which executes the primary logic defined in index.ts. Consequently, recompilation between evaluations is unnecessary. Environment variables necessary for the evaluation harness can be injected by preceding the execution command. Comprehensive documentation for evals is accessible here.

bash OPENAI_API_KEY=your-key bunx mcp-eval src/evals/evals.ts src/index.ts

Contribution Guidelines

We warmly welcome external contributions to enhance this project.

Licensing

This software component is distributed under the MIT License agreement; see the accompanying LICENSE file for definitive terms.

Attributions

• Developed utilizing the Model Context Protocol TypeScript SDK
• Interfacing with the official Trello REST API Documentation

BUSINESS MANAGEMENT TOOLS: These systems encompass applications, algorithmic solutions, controls, and methodologies employed by entities to navigate fluctuating market conditions, secure competitive placement, and elevate overall operational efficacy.

== Conceptual Overview == Management tools are functionally segmented based on organizational departments and can be categorized by core management facets: such as strategic planning instruments, process optimization utilities, data record systems, personnel management aids, decision support frameworks, and performance monitoring apparatuses. A functional decomposition typically addresses these broad organizational requirements:

Utilities for data ingestion and veracity checks across all divisions. Software for the governance and refinement of organizational workflows. Platforms for aggregating information and facilitating high-level decision synthesis. Modern management tooling has experienced rapid evolution over the past decade, driven by swift technological acceleration, making the selection of optimally suited solutions challenging for any given business context. This complexity stems from the perpetual drive to reduce expenditures while maximizing revenue, the imperative to deeply comprehend consumer requirements, and the necessity to deliver required product outcomes in the precise manner demanded by the market. In this dynamic environment, executive leadership must adopt a forward-looking, strategic viewpoint toward business management resources rather than simply adopting the newest available technology. Over-reliance on unadapted, off-the-shelf tools often results in operational instability. Therefore, business management instrumentation must be chosen with discernment and subsequently tailored to fit the organization's specific operational mandates, not forced adaptation in reverse.

== Prevalent Methodologies == In 2013, Bain & Company conducted a global assessment quantifying the deployment of various business tools, reflecting how their resultant outputs addressed regional necessities amid economic downturns and prevailing corporate statuses. The top ten ranked instruments included:

Strategic blueprinting Customer relationship orchestration (CRM) Personnel sentiment assessment programs Comparative performance analysis (Benchmarking) Integrated performance measurement systems (Balanced Scorecard) Identification of core organizational competencies External sourcing/outsourcing strategies Structured organizational transformation programs End-to-end product flow governance (Supply Chain Management) Defining corporate identity: Mission and Vision statements Market segment identification and analysis Comprehensive quality assurance frameworks (TQM)

== Enterprise Software Applications == A suite or collection of programmed instructions utilized by personnel to execute diverse corporate functions is termed business software or a business application. These programs are engineered to enhance productivity metrics, quantify performance indicators, and execute various organizational tasks with precision. The trajectory moved from foundational Management Information Systems (MIS) into comprehensive Enterprise Resource Planning (ERP) structures. Subsequently, Customer Relationship Management (CRM) capabilities were integrated, culminating in the current trend of cloud-based business management ecosystems. While a tangible relationship exists between IT investment efficacy and organizational success, two factors are critical multipliers: the proficiency of the implementation process and the judicious selection and customization of the utilized tools.

== Resources for Small-to-Medium Enterprises (SMEs) == Tools specifically tailored for SMEs are vital as they furnish mechanisms to conserve operational...