Trello-Desktop-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Trello MCP is a Model Context Protocol server providing Trello integration for any MCP-compatible client (Claude Desktop, Claude Code, Gemini CLI, etc.). It runs as a local stdio process, communicating via JSON-RPC over stdout. Credentials (TRELLO_API_KEY, TRELLO_TOKEN) are injected from environment variables at startup.

Build & Development Commands

npm run build          # Compile TypeScript → dist/
npm run clean          # Remove dist/
npm run rebuild        # Clean + build
npm run type-check     # TypeScript check without emitting

There is no test runner, linter, or formatter configured. Validate changes with npm run type-check.

Architecture

Entry Point & Protocol

src/index.ts is the MCP server entry point. It reads credentials from env vars, registers 19 tools, and routes CallToolRequest to handler functions via a switch statement. Credentials are automatically injected into every tool handler call. No console output is allowed — stdout is reserved for JSON-RPC.

Tool Modules

Each file in src/tools/ exports two things per tool: a tool definition (schema object) and a handler function. Tools are organized in phases:

Module	Tools	Domain
search.ts	trello_search	Universal search
boards.ts	trello_get_user_boards, get_board_details, list_boards, get_lists	Board operations (last two are legacy)
cards.ts	get_card, create_card, update_card, move_card	Card CRUD
lists.ts	trello_get_list_cards, trello_create_list, trello_add_comment	List ops & comments
members.ts	trello_get_member + user boards handler	Member info
advanced.ts	Board cards, card actions/attachments/checklists, board members/labels	Extended features

Trello API Client

src/trello/client.ts wraps all Trello REST API calls with:

• Exponential backoff retry (3 attempts)
• 15-second request timeout via AbortController
• Rate limit header handling
• Typed error classification (network, auth, permissions, rate limit)