# Trello MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with Trello. This server enables AI assistants like Claude, Cursor, and other MCP-compatible tools to seamlessly interact with your Trello boards, lists, and cards.

## Features

- **Board Management**: List, create, and manage Trello boards
- **List Operations**: Create and manage lists on boards
- **Card Management**: Full CRUD operations for cards (create, read, update, delete, move)
- **Label Management**: Create, update, and manage labels across boards and cards
- **Checklist Support**: Create and manage checklists with check items
- **Member Management**: Add/remove members from boards and cards
- **Comments**: Add, update, and delete comments on cards
- **Attachments**: Manage URL attachments on cards
- **Kanban View**: Get visual kanban-style board views
- **Progress Reports**: Generate completion statistics for boards
- **Real-time Health Checks**: Verify Trello API connectivity
- **Flexible Configuration**: Runtime configuration updates

## Installation

```bash
npm install
npm run build
```

## Configuration

### Get Trello API Credentials

1. Visit [https://trello.com/app-key](https://trello.com/app-key)
2. Copy your API key
3. Click the "Token" link to generate your API token
4. Copy the generated token

### Set Environment Variables

Create a `.env` file or export environment variables:

```bash
export TRELLO_API_KEY="your-api-key-here"
export TRELLO_API_TOKEN="your-api-token-here"
```

Or copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your credentials
```

## Usage

### Run the Server (stdio)

```bash
npm start
```

Or in development mode:

```bash
npm run dev
```

### Integration with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/absolute/path/to/trello_mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your-api-key-here",
        "TRELLO_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### Integration with Cursor

Configure in Cursor's MCP settings with the same command and arguments.

## Available Tools

### Board Management

- **list-boards**: Get all accessible Trello boards
- **get-board**: Get detailed information about a specific board
- **create-board**: Create a new Trello board
- **get-board-lists**: Get all lists on a board
- **create-list**: Create a new list on a board

### Card Management

- **get-card**: Get detailed information about a specific card
- **list-cards**: List all cards on a board or list
- **create-card**: Create a new card with title, description, due date, labels, and members
- **update-card**: Update an existing card
- **move-card**: Move a card to a different list (by ID or name)
- **delete-card**: Delete a card permanently
- **get-kanban-board**: Get a kanban-style view of a board
- **progress-report**: Generate progress statistics for a board

### Label Management

- **get-board-labels**: Get all labels on a board
- **create-label**: Create a new label with name and color
- **update-label**: Update label name or color
- **delete-label**: Delete a label from the board
- **add-label-to-card**: Add a label to a card
- **remove-label-from-card**: Remove a label from a card

### Checklist Management

- **get-card-checklists**: Get all checklists on a card
- **create-checklist**: Create a new checklist on a card
- **delete-checklist**: Delete a checklist
- **add-checklist-item**: Add an item to a checklist
- **update-checklist-item**: Update checklist item state (complete/incomplete)
- **delete-checklist-item**: Delete a checklist item

### Member Management

- **get-board-members**: Get all members of a board
- **get-current-member**: Get current authenticated user information
- **add-member-to-board**: Add a member to a board
- **add-member-to-card**: Assign a member to a card
- **remove-member-from-card**: Remove a member from a card

### Comments & Attachments

- **get-card-comments**: Get all comments on a card
- **add-comment-to-card**: Add a comment to a card
- **update-comment**: Update an existing comment
- **delete-comment**: Delete a comment
- **get-card-attachments**: Get all attachments on a card
- **add-attachment-to-card**: Add a URL attachment to a card
- **delete-attachment**: Delete an attachment

### Utility Tools

- **get-config**: Get current server configuration
- **update-config**: Update server configuration at runtime
- **health-check**: Check Trello API connectivity
- **help**: Display help and documentation

## Example Workflows

### 1. Create a New Project Board

```
1. Use create-board with name="My Project"
2. Use create-list to add lists: "Backlog", "In Progress", "Done"
3. Use create-card to add tasks to the Backlog list
```

### 2. Move Tasks Through Workflow

```
1. Use list-boards to find your board ID
2. Use move-card to move cards from "Backlog" to "In Progress"
3. Use move-card again to move completed cards to "Done"
```

### 3. Track Project Progress

```
1. Use get-kanban-board to see current state
2. Use progress-report to get completion statistics
3. Use list-cards to see all cards on the board
```

### 4. Manage Card Details

```
1. Use create-card with full details (name, description, due date, labels)
2. Use update-card to modify card information
3. Use get-card to retrieve current card state
```

### 5. Organize with Labels

```
1. Use get-board-labels to see available labels
2. Use create-label to add new labels with colors
3. Use add-label-to-card to tag cards
```

### 6. Track Tasks with Checklists

```
1. Use create-checklist on a card
2. Use add-checklist-item to add tasks
3. Use update-checklist-item to check off completed items
4. Use get-card-checklists to view progress
```

### 7. Collaborate with Comments

```
1. Use add-comment-to-card to discuss tasks
2. Use get-card-comments to view conversation
3. Use update-comment to edit your comments
```

## API Reference

### Create Card

```
create-card:
  name: "Card title" (required)
  listId: "list-id" (required)
  desc: "Card description" (optional)
  due: "2025-12-31" (optional, ISO date or date string)
  labels: ["label-id-1", "label-id-2"] (optional)
  members: ["member-id-1"] (optional)
  pos: "top" | "bottom" | number (optional)
```

### Move Card

```
move-card:
  cardId: "card-id" (required)
  toListId: "target-list-id" (optional if using toListName)
  toListName: "Done" (optional if using toListId, case-insensitive)
  boardId: "board-id" (required when using toListName)
```

### Progress Report

```
progress-report:
  boardId: "board-id" (required)

Returns:
  - Total cards
  - Cards per list
  - Completed count (lists with "Done" or "Complete" in name)
  - Percentage complete
```

## Development

### Project Structure

```
src/
├── types/
│   └── trello.ts          # TypeScript type definitions
├── services/
│   └── trelloApi.ts       # Trello API service wrapper
├── tools/
│   ├── boardTools.ts      # Board management tools
│   └── cardTools.ts       # Card management tools
├── resources/
│   └── trelloResources.ts # MCP resources (placeholder)
└── index.ts               # Main server entry point
```

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## Testing

The server includes a health check tool. After starting, verify connection:

```
Use the health-check tool to verify Trello API connectivity
```

## Troubleshooting

### Connection Issues

1. Verify your API key and token are correct
2. Check internet connectivity
3. Ensure you have access to the Trello API
4. Run `health-check` tool to diagnose issues

### Missing Environment Variables

If you see errors about missing TRELLO_API_KEY or TRELLO_API_TOKEN:

1. Make sure you've set the environment variables
2. Restart Claude Desktop or your MCP client after setting variables
3. Check that the paths in your MCP configuration are correct

### Permission Errors

Ensure your Trello API token has the necessary permissions for the operations you want to perform.

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License

## Credits

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) - MCP TypeScript SDK
- [axios](https://github.com/axios/axios) - HTTP client
- [zod](https://github.com/colinhacks/zod) - Schema validation

## Resources

- [Trello API Documentation](https://developer.atlassian.com/cloud/trello/)
- [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [Get Trello API Key](https://trello.com/app-key)