# Trello Task Manager MCP Server

A Python MCP server that allows AI applications to manage tasks on a real Trello board.

This project began as a local JSON Task Manager on Day 4. On Day 5, the storage layer was replaced with the Trello REST API while keeping the same MCP tool interface.

## Features

The server exposes four MCP tools:

| Tool | Action |
|---|---|
| `add_task` | Creates a Trello card in the **To Do** list |
| `list_tasks` | Lists active cards from the **To Do** list |
| `complete_task` | Moves a card to the **Done** list |
| `delete_task` | Safely archives a Trello card |

## Architecture

```text
User request
      ↓
AI application
      ↓
MCP client
      ↓
Trello Task Manager MCP Server
      ↓
Async HTTP client
      ↓
Trello REST API
      ↓
Trello board updated
      ↓
Structured MCP response
```

The MCP server defines the capabilities exposed to AI clients.

The Trello client handles:

- Authentication
- Asynchronous HTTP requests
- Timeouts
- HTTP errors
- Network failures
- Trello card operations

## Project structure

```text
task-manager-mcp/
├── .env.example
├── .gitignore
├── .python-version
├── README.md
├── get_trello_ids.py
├── main.py
├── pyproject.toml
├── trello_client.py
└── uv.lock
```

### Main files

- `main.py` — Defines the MCP server and its tools
- `trello_client.py` — Handles Trello REST API communication
- `get_trello_ids.py` — Discovers the Trello board and list IDs
- `.env.example` — Documents the required environment variables
- `.env` — Stores local credentials and is excluded from Git

## Requirements

- Python 3.11 or newer
- `uv`
- Node.js and `npx` for MCP Inspector
- A Trello account
- A Trello board with the required lists
- Trello API credentials

## Trello board structure

Create a board named:

```text
MCP Task Manager
```

Create these lists:

```text
To Do
In Progress
Done
```

Tasks are represented as Trello cards.

## Installation

Clone the repository:

```powershell
git clone YOUR_REPOSITORY_URL
cd task-manager-mcp
```

Install the dependencies:

```powershell
uv sync
```

## Environment configuration

Create your local `.env` file from the example:

```powershell
Copy-Item .env.example .env
```

Add your private configuration:

```text
TRELLO_API_KEY=your_api_key
TRELLO_TOKEN=your_token
TRELLO_BOARD_ID=your_board_id
TRELLO_TODO_LIST_ID=your_todo_list_id
TRELLO_IN_PROGRESS_LIST_ID=your_in_progress_list_id
TRELLO_DONE_LIST_ID=your_done_list_id
```

Never commit `.env`.

The public `.env.example` file must contain only empty values:

```text
TRELLO_API_KEY=
TRELLO_TOKEN=
TRELLO_BOARD_ID=
TRELLO_TODO_LIST_ID=
TRELLO_IN_PROGRESS_LIST_ID=
TRELLO_DONE_LIST_ID=
```

## Discovering Trello IDs

After adding `TRELLO_API_KEY` and `TRELLO_TOKEN` to `.env`, run:

```powershell
uv run python get_trello_ids.py
```

The script finds the board named `MCP Task Manager` and displays its board and list IDs.

Copy those IDs into `.env`.

Board and list IDs are configuration identifiers. The API token is the sensitive credential and must never be shared.

## Verify the configuration

Run:

```powershell
uv run python -c "from trello_client import validate_configuration; validate_configuration(); print('Trello configuration is valid')"
```

Expected output:

```text
Trello configuration is valid
```

## Test the Trello connection

Run:

```powershell
uv run python -c "import asyncio; from trello_client import trello_request; result = asyncio.run(trello_request('GET', '/members/me', params={'fields': 'username'})); print('Connected to Trello as:', result['username'])"
```

## Run with MCP Inspector

Start the server through MCP Inspector:

```powershell
uv run mcp dev main.py
```

Connect to the server and select **List Tools**.

The following tools should appear:

```text
add_task
list_tasks
complete_task
delete_task
```

## Tool examples

### Add a task

Tool:

```text
add_task
```

Input:

```json
{
  "title": "Prepare Day 6 MCP article",
  "description": "Add resources and reusable prompts"
}
```

The server creates a card in the Trello **To Do** list.

### List tasks

Tool:

```text
list_tasks
```

Input:

```json
{}
```

This returns the active cards from the configured **To Do** list.

### Complete a task

Tool:

```text
complete_task
```

Input:

```json
{
  "card_id": "your-trello-card-id"
}
```

The card moves from its current list to **Done**.

### Delete a task

Tool:

```text
delete_task
```

Input:

```json
{
  "card_id": "your-trello-card-id"
}
```

The server archives the card instead of permanently deleting it.

Archiving is safer because the card remains recoverable through Trello.

## Structured responses

Trello returns large card objects containing internal metadata.

The MCP server returns only the useful fields:

```json
{
  "id": "trello-card-id",
  "title": "Prepare Day 6 MCP article",
  "description": "Add resources and reusable prompts",
  "completed": false,
  "url": "https://trello.com/c/..."
}
```

This creates a stable boundary between Trello and MCP clients.

## Error handling

The server handles:

- Missing configuration
- Empty task titles
- Empty card IDs
- Invalid card IDs
- Trello HTTP errors
- Authentication failures
- Network failures
- Request timeouts

Expected failures are converted into clear MCP tool errors instead of exposing long internal tracebacks.

## Security

The following values must never be committed or published:

- Trello API token
- Real `.env` contents
- Credentials in screenshots
- Credentials in documentation
- Credentials in Git history

Before committing, verify that `.env` is ignored:

```powershell
git check-ignore -v .env
```

If a token is accidentally committed, revoke it immediately and generate a new one.

## Local storage versus Trello

### Day 4

```text
MCP tool
    ↓
Local Python function
    ↓
tasks.json
```

### Day 5

```text
MCP tool
    ↓
Trello API client
    ↓
Trello REST API
    ↓
Real Trello card
```

The public tool names remain familiar even though the backend implementation changed completely.

## Key lessons

This project demonstrates:

- Building MCP tools with FastMCP
- Connecting MCP to a real external platform
- REST API authentication
- Secure environment-variable configuration
- Asynchronous HTTP requests with `httpx`
- Request timeouts
- Controlled API error handling
- Structured MCP responses
- Separation between MCP logic and integration logic
- Safe deletion through archiving
- Keeping an external system as the source of truth

## Next step

Day 6 will extend this server with:

- MCP resources
- Resource URIs
- Board and card context
- Reusable prompts
- Daily planning workflows
- Weekly task-summary workflows

Day 5 gave the server the ability to act.

Day 6 will give it reusable context and guided workflows.