# Trello MCP Server

A Model Context Protocol (MCP) server that provides Claude with tools to interact with Trello boards, lists, and cards through the Trello REST API.

## Features

### Core Functionality
- **Board Management**: List boards, get board details and metadata
- **List Operations**: Retrieve lists, create new lists within boards
- **Card Management**: Create, update, delete, and move cards between lists
- **Member Management**: Add/remove members from boards and cards
- **Labels & Checklists**: Manage card labels and checklist items

### Technical Features
- TypeScript implementation with full type safety
- Comprehensive error handling and validation
- Rate limiting compliance for Trello API
- Secure authentication using API key/token
- Integration with Popular Agentic IDE via MCP protocol

## Prerequisites

- Node.js 18+ and npm
- Trello account with API access
- Claude Desktop application

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd trello-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Authentication Setup

1. **Get Trello API Credentials**:
   - Visit https://trello.com/app-key to get your API key
   - Generate a token by visiting: `https://trello.com/1/authorize?expiration=never&scope=read,write,account&response_type=token&name=Server%20Token&key=YOUR_API_KEY`

2. **Configure Environment**:
   Create a `.env` file in the project root:
   ```env
   TRELLO_API_KEY=your_api_key_here
   TRELLO_TOKEN=your_token_here
   ```

## Integration Setup

### Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

#### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

#### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["/path/to/trello-mcp/dist/index.js"],
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Docker Desktop Integration

Docker Desktop (v4.38+) includes built-in MCP server support through the Docker MCP Catalog and Toolkit. This provides the easiest way to run and manage MCP servers.

#### Option 1: Using Docker Desktop's Built-in MCP Support (Recommended)

1. **Enable MCP in Docker Desktop**:
   - Open Docker Desktop (ensure version 4.38 or later)
   - Go to **Extensions** → **Browse** → Search for "MCP" 
   - Install the **Docker MCP Catalog and Toolkit** extension

2. **Publish to Docker Hub's MCP Catalog**:
   ```bash
   # Build and tag for MCP catalog
   docker build -t mcp/trello-server .
   docker push mcp/trello-server
   ```

3. **Configure in Claude Desktop with Docker MCP**:
   ```json
   {
     "mcpServers": {
       "trello": {
         "command": "docker",
         "args": [
           "run", "--rm", "-i",
           "--env-file", ".env",
           "mcp/trello-server"
         ]
       }
     }
   }
   ```

4. **Use with Ask Gordon (Docker AI)**:
   Create `gordon-mcp.yml` in your project directory:
   ```yaml
   version: '3.8'
   services:
     trello-mcp:
       image: mcp/trello-server
       environment:
         - TRELLO_API_KEY=${TRELLO_API_KEY}
         - TRELLO_TOKEN=${TRELLO_TOKEN}
       volumes:
         - ./logs:/app/logs
   ```

   Then use Docker AI commands:
   ```bash
   # Ask Gordon to help with Trello management
   docker ai "Show me my Trello boards and create a new development task"
   ```

#### Option 2: Traditional Docker Setup

Create a `Dockerfile` in your project root:

```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs
RUN adduser -S mcp -u 1001
RUN chown -R mcp:nodejs /app
USER mcp

EXPOSE 3000

CMD ["node", "dist/index.js"]
```

Build and run the container:

```bash
# Build the image
docker build -t trello-mcp-server .

# Run with Docker MCP Toolkit (secure credential management)
docker run -d \
  --name trello-mcp \
  --env-file .env \
  -p 3000:3000 \
  trello-mcp-server

# Or use docker-compose.yml:
```

Create `docker-compose.yml`:

```yaml
version: '3.8'
services:
  trello-mcp:
    build: .
    container_name: trello-mcp-server
    environment:
      - TRELLO_API_KEY=${TRELLO_API_KEY}
      - TRELLO_TOKEN=${TRELLO_TOKEN}
      - LOG_LEVEL=info
      - API_TIMEOUT=10000
    ports:
      - "3000:3000"
    restart: unless-stopped
    volumes:
      - ./logs:/app/logs
    networks:
      - mcp-network

networks:
  mcp-network:
    driver: bridge
```

Run with Docker Compose:

```bash
# Set environment variables in .env file, then:
docker-compose up -d
```

#### Benefits of Docker Desktop MCP Integration

- **Built-in Security**: OAuth support and secure credential storage
- **One-Click Setup**: Seamless integration with Claude, Cursor, VSCode, and other MCP clients
- **Cross-Platform**: Consistent behavior across different architectures
- **Isolation**: Memory, network, and disk isolation for production-ready security
- **Discovery**: Access to 100+ verified MCP tools from Docker Hub's MCP Catalog

### Cursor IDE Integration

In Cursor, you can set up the MCP server for AI-assisted development:

1. **Install Cursor Extension** (if available):
   - Open Cursor IDE
   - Go to Extensions marketplace
   - Search for "MCP" or "Model Context Protocol"

2. **Configure MCP Server**:
   Create `.cursor/mcp-config.json` in your workspace:

```json
{
  "mcpServers": {
    "trello": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/trello-mcp",
      "env": {
        "TRELLO_API_KEY": "your_api_key_here",
        "TRELLO_TOKEN": "your_token_here"
      }
    }
  }
}
```

3. **Use with Cursor AI**:
   - Open Cursor's AI chat panel
   - The Trello MCP tools should be available for context
   - Ask questions like: "Show me my Trello boards and help me organize my tasks"

### Windsurf IDE Integration

For Windsurf IDE integration:

1. **Project Configuration**:
   Create `.windsurf/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "trello": {
        "command": "node",
        "args": ["dist/index.js"],
        "cwd": "${workspaceFolder}",
        "env": {
          "TRELLO_API_KEY": "your_api_key_here",
          "TRELLO_TOKEN": "your_token_here"
        }
      }
    }
  },
  "ai": {
    "providers": {
      "claude": {
        "mcpServers": ["trello"]
      }
    }
  }
}
```

2. **Workspace Setup**:
   Add to your `.windsurf/workspace.json`:

```json
{
  "name": "Trello MCP Development",
  "description": "Development workspace with Trello integration",
  "mcpServers": ["trello"],
  "tools": {
    "trello": {
      "enabled": true,
      "autoStart": true
    }
  }
}
```

3. **Usage in Windsurf**:
   - The AI assistant will have access to Trello tools
   - Use natural language commands in the AI chat
   - Example: "Create a development task board and add cards for the current project features"

### Development Container (DevContainer)

For consistent development environments, create `.devcontainer/devcontainer.json`:

```json
{
  "name": "Trello MCP Development",
  "build": {
    "dockerfile": "../Dockerfile.dev"
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install && npm run build",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-vscode.vscode-typescript-next",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ],
      "settings": {
        "mcp.servers": {
          "trello": {
            "command": "node",
            "args": ["dist/index.js"],
            "env": {
              "TRELLO_API_KEY": "${TRELLO_API_KEY}",
              "TRELLO_TOKEN": "${TRELLO_TOKEN}"
            }
          }
        }
      }
    }
  },
  "remoteEnv": {
    "TRELLO_API_KEY": "${localEnv:TRELLO_API_KEY}",
    "TRELLO_TOKEN": "${localEnv:TRELLO_TOKEN}"
  }
}
```

Create `Dockerfile.dev`:

```dockerfile
FROM node:18

WORKDIR /workspace

# Install global tools
RUN npm install -g @modelcontextprotocol/inspector typescript

# Set up development environment
COPY package*.json ./
RUN npm install

# Copy source code
COPY . .

# Expose MCP server port
EXPOSE 3000

CMD ["npm", "run", "dev"]
```

## Available Tools

### Board Operations
- `list_boards` - Get all boards accessible to the user
- `get_board` - Get detailed information about a specific board
- `get_board_members` - List members of a board

### List Operations  
- `get_lists` - Get all lists in a board
- `create_list` - Create a new list in a board
- `update_list` - Update list properties (name, position)

### Card Operations
- `get_cards` - Get cards from a board or list
- `create_card` - Create a new card
- `update_card` - Update card properties (name, description, due date)
- `move_card` - Move card to different list
- `delete_card` - Delete a card
- `add_card_member` - Add member to a card
- `remove_card_member` - Remove member from a card

### Label Operations
- `get_labels` - Get available labels for a board
- `add_card_label` - Add label to a card
- `remove_card_label` - Remove label from a card

### Checklist Operations
- `get_card_checklists` - Get checklists on a card
- `create_checklist` - Create a new checklist on a card
- `add_checklist_item` - Add item to a checklist
- `update_checklist_item` - Update checklist item (mark complete/incomplete)

## Development

### Project Structure
```
trello-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── trello-client.ts  # Trello API client
│   ├── tools/            # MCP tool implementations
│   │   ├── boards.ts
│   │   ├── lists.ts
│   │   ├── cards.ts
│   │   └── labels.ts
│   └── types/            # TypeScript type definitions
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Scripts
- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Run in development mode with auto-reload
- `npm run start` - Start the MCP server
- `npm run test` - Run tests

### Testing
```bash
# Install the MCP Inspector for testing
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector node dist/index.js
```

## Usage Examples

Once integrated with Claude Desktop, you can use natural language to interact with Trello:

- "Show me all my Trello boards"
- "Create a new card called 'Fix login bug' in the 'To Do' list of my Development board"
- "Move the card 'Review PR #123' to the 'Done' list"
- "Add the 'Priority' label to the card about the database migration"
- "List all cards in my Personal board that are due this week"

## Error Handling

The server includes comprehensive error handling for:
- Network connectivity issues
- Invalid API credentials
- Rate limiting (429 errors)
- Invalid board/list/card IDs
- Permission errors

## Security Notes

- API credentials are passed via environment variables
- No credentials are logged or stored in plain text
- All API requests use HTTPS
- Rate limiting is respected to avoid API abuse

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper TypeScript types
4. Add tests for new functionality
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Check the Trello API documentation: https://developer.atlassian.com/cloud/trello/rest
- Review MCP documentation: https://modelcontextprotocol.io
- Open an issue in this repository