trello-mcp 1.0.0

package/README.md

@@ -0,0 +1,394 @@
+# Trello MCP Server
+
+A comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Trello. Manage boards, lists, cards, checklists, labels, and members through any MCP-compatible AI assistant.
+
+**Works with:** Claude Code, Claude Desktop, Cursor, Windsurf, Cody, OpenCode, and any other MCP client.
+
+## Features
+
+- **Board Management**: Create, list, update, and archive boards
+- **List Management**: Create, move, and archive lists
+- **Card Operations**: Full CRUD operations, search, comments, attachments
+- **Checklist Support**: Create checklists, add/update/complete items
+- **Label Management**: Create, update, and assign labels
+- **Member Management**: View members, assign to cards
+- **Search**: Full-text search with Trello search operators
+
+---
+
+## Quick Start
+
+### Step 1: Get Your Trello API Credentials (2 minutes)
+
+You need two things from Trello: an **API Key** and a **Token**.
+
+#### Step 1a: Create a Trello Power-Up
+
+1. Go to **https://trello.com/power-ups/admin**
+2. Log in to Trello if prompted
+3. Click the **"New"** button (top right)
+4. Fill in the **"New App"** form:
+   - **App name**: Anything you want (e.g., `trellomcp`)
+   - **Workspace**: Select any workspace you belong to
+   - **Email**: Your email *(only Trello sees this, not us)*
+   - **Support contact**: Your email *(only Trello sees this, not us)*
+   - **Author**: Your name
+   - **Iframe connector URL**: **Leave this blank**
+5. Click **"Create"**
+
+#### Step 1b: Generate Your API Key
+
+1. After creating the app, you'll land on the app settings page
+2. Click **"API key"** in the left sidebar (if not already selected)
+3. Click the **"Generate a new API key"** button
+4. You'll now see three fields:
+   - **API key** - ✅ **Copy this!** This is your `TRELLO_API_KEY`
+   - **Allowed origins** - ❌ Leave empty (not needed)
+   - **Secret** - ❌ Ignore this (only for OAuth, we don't use it)
+
+#### Step 1c: Generate Your Token
+
+1. On the same page, find the text that says *"manually generate a Token"*
+2. Click the **"Token"** link in that text
+3. You'll see an authorization page asking *"Would you like to give the following application access to your account?"*
+   - It shows your app name and Trello account
+   - Scroll down and click **"Allow"**
+4. You'll see a page that says: *"You have granted access to your Trello account via the token below:"*
+5. **Copy the token displayed** - this is your `TRELLO_TOKEN`
+
+> **Alternative:** If you can't find the Token link, visit this URL directly (replace `YOUR_API_KEY`):
+> ```
+> https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY
+> ```
+
+**You now have both credentials:**
+- `TRELLO_API_KEY` - from Step 1b
+- `TRELLO_TOKEN` - from Step 1c
+
+---
+
+### Step 2: Install the MCP Server
+
+```bash
+npm install -g trello-mcp-server
+```
+
+Or from source:
+```bash
+git clone https://github.com/anthropics/trello-mcp-server.git
+cd trello-mcp-server
+npm install
+npm run build
+```
+
+---
+
+### Step 3: Configure Your MCP Client
+
+Choose your client below:
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add trello -e TRELLO_API_KEY=your-key -e TRELLO_TOKEN=your-token -- trello-mcp-server
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "trello-mcp-server",
+      "env": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "trello-mcp-server",
+      "env": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add to `~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "trello-mcp-server",
+      "env": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>OpenCode</b></summary>
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "trello": {
+      "type": "local",
+      "command": ["trello-mcp-server"],
+      "environment": {
+        "TRELLO_API_KEY": "your-api-key",
+        "TRELLO_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Other / Manual</b></summary>
+
+```bash
+TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token trello-mcp-server
+```
+
+</details>
+
+---
+
+### Step 4: Verify It Works
+
+Ask your AI assistant:
+> "List my Trello boards"
+
+It should respond with your Trello boards!
+
+---
+
+## Troubleshooting
+
+### "Command not found"
+
+Find the full path:
+```bash
+which trello-mcp-server   # macOS/Linux
+where trello-mcp-server   # Windows
+```
+
+Then use the full path in your config (e.g., `/usr/local/bin/trello-mcp-server`).
+
+### "Invalid API key" or "Invalid token"
+
+- Check you copied the full key (32 chars) and token (64 chars)
+- No extra spaces
+- Token not revoked at https://trello.com/your/account
+
+### Tools not showing up
+
+- Restart your MCP client after config changes
+- Check JSON syntax is valid (use a JSON validator)
+- Check the server runs manually: `TRELLO_API_KEY=x TRELLO_TOKEN=y trello-mcp-server --help`
+
+---
+
+## What You Can Do
+
+Example prompts:
+
+### Boards
+- "List all my Trello boards"
+- "Create a new board called 'Project Alpha'"
+- "Show me the lists on my 'Work' board"
+
+### Cards
+- "Create a card called 'Review PR #123' in the 'To Do' list"
+- "Move the 'Homepage redesign' card to 'Done'"
+- "Search for cards containing 'bug' due this week"
+
+### Checklists
+- "Add a checklist to the 'Release v2.0' card with items: Tests, Docs, Deploy"
+- "Mark 'Tests' as complete"
+
+### Labels & Members
+- "Add the 'Urgent' label to the 'Fix bug' card"
+- "Assign @john to the 'Design review' card"
+
+### Comments
+- "Add a comment to the card saying 'Waiting for client feedback'"
+
+---
+
+## All Available Tools (39 total)
+
+### Boards (6)
+- `trello_list_boards` - List all boards
+- `trello_get_board` - Get board with lists
+- `trello_create_board` - Create board
+- `trello_update_board` - Update board
+- `trello_get_board_labels` - Get board labels
+- `trello_get_board_members` - Get board members
+
+### Lists (6)
+- `trello_create_list` - Create list
+- `trello_update_list` - Update list
+- `trello_get_list_cards` - Get cards in list
+- `trello_archive_all_cards` - Archive all cards
+- `trello_move_all_cards` - Move all cards
+- `trello_move_list` - Move list to board
+
+### Cards (17)
+- `trello_get_card` - Get card details
+- `trello_create_card` - Create card
+- `trello_update_card` - Update card
+- `trello_delete_card` - Delete card
+- `trello_search_cards` - Search cards
+- `trello_copy_card` - Copy card
+- `trello_add_comment` - Add comment
+- `trello_get_card_comments` - Get comments
+- `trello_update_comment` - Update comment
+- `trello_delete_comment` - Delete comment
+- `trello_add_card_label` - Add label
+- `trello_remove_card_label` - Remove label
+- `trello_assign_member` - Assign member
+- `trello_remove_member` - Remove member
+- `trello_add_attachment` - Add attachment
+- `trello_get_attachments` - Get attachments
+- `trello_delete_attachment` - Delete attachment
+
+### Labels (3)
+- `trello_create_label` - Create label
+- `trello_update_label` - Update label
+- `trello_delete_label` - Delete label
+
+### Checklists (8)
+- `trello_create_checklist` - Create checklist
+- `trello_update_checklist` - Update checklist
+- `trello_delete_checklist` - Delete checklist
+- `trello_get_checklist` - Get checklist
+- `trello_add_checklist_item` - Add item
+- `trello_update_checklist_item` - Update item
+- `trello_delete_checklist_item` - Delete item
+- `trello_copy_checklist` - Copy checklist
+
+### Members (5)
+- `trello_get_me` - Get current user
+- `trello_get_member` - Get member info
+- `trello_get_member_boards` - Get member's boards
+- `trello_get_member_cards` - Get member's cards
+- `trello_search_members` - Search members
+
+---
+
+## Search Operators
+
+Use Trello's search syntax with `trello_search_cards`:
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| `@me` | `@me` | My cards |
+| `#label` | `#bug` | Cards with label |
+| `board:` | `board:Dev` | On specific board |
+| `list:` | `list:"To Do"` | In specific list |
+| `is:open` | `is:open` | Open cards |
+| `due:day` | `due:week` | Due soon |
+| `due:overdue` | `due:overdue` | Past due |
+| `has:attachments` | `has:checklist` | Has feature |
+
+Example: `@me due:week is:open #urgent`
+
+---
+
+## HTTP Server Mode
+
+For web integrations or remote access:
+
+```bash
+TRELLO_API_KEY=x TRELLO_TOKEN=y TRANSPORT=http PORT=3000 trello-mcp-server
+```
+
+Server available at `http://localhost:3000/mcp`
+
+---
+
+## Development
+
+```bash
+npm install
+TRELLO_API_KEY=x TRELLO_TOKEN=y npm run dev   # Dev mode with auto-reload
+npm run build                                   # Build for production
+npm run inspect                                 # Test with MCP Inspector
+```
+
+---
+
+## Security & Credentials
+
+### How are my credentials stored?
+
+Your Trello API key and token are stored **locally on your machine** in your MCP client's config file:
+
+| Client | Config Location |
+|--------|-----------------|
+| Claude Code | `~/.claude/settings.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Cursor | `~/.cursor/mcp.json` |
+
+The MCP server **never stores your credentials** - it only reads them from environment variables that your MCP client provides when starting the server.
+
+### Do credentials expire?
+
+- **API Key**: Never expires
+- **Token**: Never expires (we use `expiration=never`)
+
+You can revoke your token anytime at https://trello.com/your/account
+
+### Security best practices
+
+- **Never share your token** - it provides full access to your Trello account
+- **Don't commit config files** with credentials to git
+- **Revoke and regenerate** if you accidentally expose your token
+- The token has `read,write` scope - it can read and modify your boards
+
+---
+
+## License
+
+MIT

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Constants for Trello MCP Server
+ */
+export declare const TRELLO_API_BASE = "https://api.trello.com/1";
+export declare const CHARACTER_LIMIT = 25000;
+export declare const DEFAULT_LIMIT = 50;
+export declare const MAX_LIMIT = 1000;
+export declare const LABEL_COLORS: readonly ["green", "yellow", "orange", "red", "purple", "blue", "sky", "lime", "pink", "black"];
+export declare const POSITION: {
+    readonly TOP: "top";
+    readonly BOTTOM: "bottom";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAG1D,eAAO,MAAM,eAAe,QAAQ,CAAC;AAGrC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,SAAS,OAAO,CAAC;AAG9B,eAAO,MAAM,YAAY,iGAWf,CAAC;AAGX,eAAO,MAAM,QAAQ;;;CAGX,CAAC"}

package/dist/constants.js

@@ -0,0 +1,28 @@
+/**
+ * Constants for Trello MCP Server
+ */
+export const TRELLO_API_BASE = "https://api.trello.com/1";
+// Maximum characters in a response before truncation
+export const CHARACTER_LIMIT = 25000;
+// Default pagination limits
+export const DEFAULT_LIMIT = 50;
+export const MAX_LIMIT = 1000;
+// Valid label colors for Trello
+export const LABEL_COLORS = [
+    "green",
+    "yellow",
+    "orange",
+    "red",
+    "purple",
+    "blue",
+    "sky",
+    "lime",
+    "pink",
+    "black",
+];
+// Card position helpers
+export const POSITION = {
+    TOP: "top",
+    BOTTOM: "bottom",
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAE1D,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,4BAA4B;AAC5B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAE9B,gCAAgC;AAChC,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,KAAK;IACL,MAAM;IACN,MAAM;IACN,OAAO;CACC,CAAC;AAEX,wBAAwB;AACxB,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;CACR,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Trello MCP Server
+ *
+ * A comprehensive MCP server for managing Trello boards, lists, cards,
+ * checklists, labels, and members.
+ *
+ * Features:
+ * - Full board, list, and card management
+ * - Checklist creation and management
+ * - Label management
+ * - Member assignment
+ * - Card search with Trello search operators
+ * - Attachment handling
+ * - Comment management
+ *
+ * Authentication:
+ * - Set TRELLO_API_KEY and TRELLO_TOKEN environment variables
+ * - Get your API key from: https://trello.com/power-ups/admin
+ * - Generate a token from: https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=YOUR_API_KEY
+ *
+ * Usage:
+ * - stdio transport (default): node dist/index.js
+ * - HTTP transport: TRANSPORT=http PORT=3000 node dist/index.js
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}