trello-mcp

trello-mcp

A self-hostable Model Context Protocol server that lets MCP-compatible clients work with Trello cards, lists, labels, attachments, checklists, members, and card activity.

The project is intentionally self-hostable and reusable. Contributions, adaptations, and focused issue reports are welcome.

The roadmap is, of course, tracked on Trello, and trello-mcp helps keep it up to date: trello-mcp roadmap.

Disclaimer

trello-mcp is an independent, community-maintained project. It is not an official Trello or Atlassian product, service, or MCP implementation, and it is not affiliated with, endorsed by, or sponsored by Trello or Atlassian.

This project exists to make it easier for MCP-compatible LLM clients to interface with Trello through Trello's public API and user-provided API credentials.

Looking for Trello's official hosted MCP server? Visit Trello MCP and use the endpoint documented by Trello: https://mcp.trello.com/v1.

Documentation

The complete project documentation is available at trello-mcp.com:

• Get started
• Create a Trello API key and token
• Set up your MCP client
• Browse the tool catalog
• Review API coverage and non-goals
• Understand Security & Data
• Operate a running deployment
• Troubleshoot an installation
• Official MCP Registry installation, releases, and recovery

Features

Board Discovery

• List boards visible to the authenticated Trello member.
• Read basic board metadata.
• List open, closed, or all lists on a board.
• List open, closed, visible, or all cards on a board.
• List board labels, members, and memberships.
• Create, inspect, update, and delete board labels.
• Create, inspect, rename, archive, unarchive, and move lists between boards.

Card Workflows

• Read cards by id, short id, or Trello card URL.
• Create cards with title, description, due date, position, members, and labels.
• Update card metadata including title, description, due date, due completion, and archived state.
• Move cards between lists or boards.
• Apply and remove existing labels on cards.
• Permanently delete cards only when explicitly requested.

Card Context

• List cards in a Trello list.
• List card attachments, inspect individual attachments, add public URL attachments, and upload server-local files from an explicitly configured directory.
• List, create, rename, and delete card checklists, and manage checklist items.
• List card members and add or remove members.
• Read card actions and activity history.
• Add, edit, and delete Trello card comments.

Search Workflows

• Search Trello cards, boards, members, and workspaces by natural language terms.
• Scope search results to specific boards, cards, or workspaces.
• Look up Trello members by name or username before assignment.
• Read member profiles, assigned cards, boards, and workspaces.

Workspace Discovery

• List Trello workspaces visible to the authenticated member.
• Read workspace metadata, boards, and members.

Self-Hosted Runtime

• Run with Docker Compose using the published GHCR image.
• Build locally with a separate Compose file.
• Use Streamable HTTP for container deployments.
• Use stdio for local MCP clients that launch the server as a child process.
• Keep stdio logs on stderr so local MCP clients receive protocol-only stdout.
• Expose HTTP health and readiness endpoints.
• Optionally require a bearer token for HTTP MCP endpoint requests.
• Validate config, tool input, and Trello API responses with Zod.
• Redact Trello credentials from logs.
• Run typecheck, lint, build, tests, and coverage in GitHub Actions.

Quick Start

1. Get Trello API Credentials

Trello API keys are created from an app in Trello's App Admin Portal. Each person running this server should use their own Trello account and token. Follow the dedicated Trello API credentials guide for the current, security-focused walkthrough.

In short: create or select an app at trello.com/apps/admin, generate a key from its API Key tab, then use the nearby Token link to review and authorize access for the intended Trello member.

You will use those values as:

TRELLO_API_KEY=your-api-keyTRELLO_TOKEN=your-token

2. Choose an Install Path

Option A: Run the Published Docker Image

Use this path if you just want to run the server. It pulls the prebuilt image from GHCR and does not build anything locally.

git clone https://github.com/enthouan/trello-mcp.gitcd trello-mcpcp .env.example .env

Edit .env and replace the placeholder values:

TRELLO_API_KEY=your-api-keyTRELLO_TOKEN=your-tokenTRANSPORT=httpLOG_LEVEL=infoTRELLO_RATE_LIMIT_CAPACITY=100TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000TRELLO_RETRY_MAX_ATTEMPTS=3TRELLO_RETRY_BASE_DELAY_MS=100TRELLO_RETRY_MAX_DELAY_MS=2000# MCP_AUTH_TOKEN=optional-shared-secretTRELLO_MCP_HOST_BIND_IP=127.0.0.1TRELLO_MCP_HOST_PORT=3000TRELLO_MCP_IMAGE_TAG=latestTRELLO_MCP_NETWORK=trello-mcp_network

Start the published image:

docker compose up -d --wait --wait-timeout 120

The default docker-compose.yml uses:

ghcr.io/enthouan/trello-mcp:latest

Docker Compose values such as image tag, host bind IP, host port, and network name can be overridden with environment variables or the .env file. The compose files document their defaults at the top; for example, TRELLO_MCP_IMAGE_TAG defaults to the latest tag in docker-compose.yml (latest follows the main branch, and release tags such as X.Y and X.Y.Z are available for versioned deployments), TRELLO_MCP_HOST_BIND_IP defaults to 127.0.0.1 for local-only access, TRELLO_MCP_HOST_PORT defaults to 3000 and maps that host port to the container's fixed internal 3000 listener, while TRELLO_MCP_NETWORK defaults to trello-mcp_network. Set TRELLO_MCP_HOST_BIND_IP=0.0.0.0 only when you intentionally want Docker to publish the service on all host interfaces, such as for LAN access.

Set MCP_AUTH_TOKEN to require Authorization: Bearer <token> on HTTP MCP requests to /mcp. Leave it unset for the default unauthenticated local behavior. Health and readiness endpoints remain unauthenticated for container and reverse-proxy checks.

Container health follows TRANSPORT: HTTP checks /healthz on PORT (default 3000), while stdio uses process liveness and lets the attached MCP client check protocol responsiveness. Compose inherits this image health check.

Keep the Trello rate-limit and retry values at their defaults unless logs show trello rate limit wait or trello request rate limited; retrying during large workflows. Lower the capacity for shared tokens or constrained deployments; raise it carefully only after narrowing the workflow's board, card, field, and pagination scope.

For reproducible deployments, prefer an exact X.Y.Z tag. Published Docker image tags use these conventions:

You can also run the published image directly without Compose:

docker run --rm -p 127.0.0.1:3000:3000 \  -e TRELLO_API_KEY=your-api-key \  -e TRELLO_TOKEN=your-token \  ghcr.io/enthouan/trello-mcp:latest

Option B: Build Locally from Source

Use this path if you want to develop the project, test local changes, or build the Docker image yourself.

Local development uses Node.js 24.x and the pinned [email protected] package manager through Corepack.

git clone https://github.com/enthouan/trello-mcp.gitcd trello-mcpcp .env.example .env

Edit .env with your Trello credentials, then build and run locally:

docker compose -f docker-compose.local.yml up --build -d --wait --wait-timeout 120

This uses docker-compose.local.yml, which builds from the local Dockerfile and tags the image as trello-mcp:local.

For a non-Docker local build:

corepack enablecorepack prepare [email protected] --activatecorepack pnpm install --frozen-lockfilecorepack pnpm build:clean

Then run the compiled server directly:

TRELLO_API_KEY=your-api-key TRELLO_TOKEN=your-token TRANSPORT=stdio node dist/index.js

Treat the token like a password. Do not commit it, paste it in logs, or share it in PRs.

3. Connect Your MCP Client

Choose the transport by where the server runs:

The Set up your MCP client guide has current, sanitized examples for Claude Desktop, Claude Code, Codex CLI, VS Code, OpenCode, MCP Inspector, and other manual clients. It also covers restart requirements, HTTP bearer support, secret handling, and tested limitations.

For dated client versions and evidence, see MCP Client Compatibility.

4. Verify

If you chose Streamable HTTP, check the server:

curl http://127.0.0.1:3000/healthzcurl http://127.0.0.1:3000/readyz

If you changed TRELLO_MCP_HOST_PORT, replace 3000 with that host port. If you changed TRELLO_MCP_HOST_BIND_IP from 127.0.0.1, use a hostname or IP address that can reach the bound host interface.

Then confirm the MCP client discovers the current 77-tool surface. With an intentional read-only credential check, call auth_whoami or auth_token_info from the client. Do not make a write-side Trello call just to prove setup.

Trello Credentials

This server currently uses Trello API key + token authentication. Follow the dedicated Trello API credentials guide for a security-focused walkthrough, with links to Trello's official App Admin Portal, authorization, and revocation documentation.

Use the read-only auth_whoami and auth_token_info tools to verify which Trello member the configured credentials authenticate as and to inspect the configured token's owner, expiration, and permissions. These tools are diagnostics only; this server does not implement OAuth redirects, token creation, token refresh, token revocation, or other token lifecycle management.

Set up your MCP client

Use the canonical Set up your MCP client guide for transport selection and client-specific configuration. Keep Trello credentials in the stdio child environment or on the HTTP server; an HTTP client needs only the /mcp endpoint and, when MCP_AUTH_TOKEN is enabled, a supported bearer-header configuration.

The compatibility record distinguishes an official-doc review from a real client connection, tool discovery, and an actual Trello workflow.

Environment

See the configuration reference for deployment-specific applicability, secret handling, rate-limit tuning, Compose controls, and local attachment-upload requirements.

Live Trello Smoke Tests

Normal tests are mocked and offline. corepack pnpm test, corepack pnpm test:coverage, and the default CI workflow never require Trello credentials and never contact Trello.

For release validation against real Trello, use the explicit live smoke command:

TRELLO_LIVE_SMOKE=1 \TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm smoke:live

You may use TRELLO_LIVE_SMOKE_BOARD_URL instead of TRELLO_LIVE_SMOKE_BOARD_ID; Trello trello.com/b/... board URLs are normalized to their short link, then the harness resolves the canonical board id with board_get before creating anything. Non-board URLs are rejected without logging their raw value or query string. TRELLO_LIVE_SMOKE_RUN_ID is optional and is included in temporary artifact names when set.

Set TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 when output may be published. The harness then verifies Trello reports the board as public before recording its identity or performing writes. This is optional for local private disposable-board validation.

Safety model:

• The command exits before any Trello request unless TRELLO_LIVE_SMOKE=1, Trello credentials, and a smoke board id or URL are all present.
• The configured board should be a disposable board reserved for validation, not an active production board.
• The harness creates uniquely named temporary lists, one card, one label, one checklist, one checklist item, and one comment. It deletes the card and label, archives the temporary lists, and verifies that no open temporary lists, cards, or labels remain.
• Cleanup runs even when an intermediate validation step fails. It also searches for uniquely prefixed lists, cards, and labels that Trello created before a response validation failure could track them. Cleanup failures are reported and cause the command to fail.
• The harness invokes the existing tool handlers with a real TrelloClient, so tool input validation, Trello response validation, retry/rate-limit handling, and credential redaction stay on the normal code path.
• The harness does not log API keys, tokens, credential-bearing URLs, raw environment objects, or raw request data.

The smoke flow validates representative v1.0 workflows:

• Auth and discovery: auth_whoami, auth_token_info, list_boards, board reads, lists, cards, labels, members, memberships, and custom-field discovery.
• List and card writes: disposable list creation/rename/archive, card create/read/update/due-date/position/archive/restore/move/delete.
• Checklist and item behavior: checklist creation/rename/deletion plus item create/list/update/check/delete.
• Labels and members: disposable label create/read/update/apply/remove/delete, plus authenticated-member assignment/removal when that member is visible on the smoke board.
• Card activity: comment create/update/list/delete on the disposable card.

Live Trello Regression Tests

corepack pnpm smoke:live is the shallow release smoke check: it proves the most important workflow can authenticate, create disposable artifacts, mutate them, and clean up. corepack pnpm regression:live is the broader opt-in release-validation suite. It walks the public MCP tool surface by domain, reports live coverage against the registered tool catalog, and makes skipped or missing live coverage visible.

The regression suite has a separate opt-in gate from smoke tests:

TRELLO_LIVE_REGRESSION=1 \TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm regression:live

Use TRELLO_LIVE_REGRESSION_BOARD_URL instead of TRELLO_LIVE_REGRESSION_BOARD_ID when a trello.com/b/... board URL is more convenient. Non-board URLs are rejected before any Trello request and without logging raw query strings.

Set TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1 when output or the JSON report may be published. The harness then verifies Trello reports every configured board as public before recording its identity or performing writes. Local private disposable-board runs can omit this flag and keep their output private.

Set TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID or TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_URL when you want live coverage for cross-board list moves. The secondary board is optional for local runs; when it is absent, list_move_to_board is reported as an intentional runtime skip instead of missing coverage. When it is present, the suite resolves it with board_get, confirms the token can see it through list_boards, verifies it is open and different from the primary board, then moves only disposable lists between the two boards.

Targeted runs are useful when debugging a domain or one tool:

TRELLO_LIVE_REGRESSION=1 \TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm regression:live --domain cards

TRELLO_LIVE_REGRESSION=1 \TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm regression:live --tool card_attachment_upload

TRELLO_LIVE_REGRESSION=1 \TRELLO_LIVE_REGRESSION_BOARD_ID=your-primary-disposable-board-id-or-short-link \TRELLO_LIVE_REGRESSION_SECONDARY_BOARD_ID=your-secondary-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm regression:live --tool list_move_to_board

You may also use TRELLO_LIVE_REGRESSION_DOMAINS=cards,attachments and TRELLO_LIVE_REGRESSION_TOOLS=card_get,card_update. Supported domains are auth, boards, lists, cards, labels, checklists, members, workspaces, search, custom-fields, comments-actions, and attachments.

Set TRELLO_LIVE_REGRESSION_REPORT_JSON=reports/live-regression.json to emit a machine-readable report in addition to the human-readable terminal report. The report groups tools by domain and shows:

• covered: tool handlers successfully exercised against Trello.
• skipped: intentional runtime skips, such as no visible workspace, no board custom fields, or upload coverage not configured.
• unsupported: non-goal live cases that are intentionally outside regression coverage, such as board_create.
• missing: selected public tools with no regression coverage classification. Missing coverage fails the command so new public tools do not silently disappear from release validation.
• cleanup status, including attempted/completed cleanup steps and any remaining prefix-matched open artifacts.

Regression safety model:

• The command exits before any Trello request unless TRELLO_LIVE_REGRESSION=1, Trello credentials, and a regression board id or URL are all present.
• The configured board should be a disposable board reserved for validation, not an active production board.
• The optional secondary board should also be disposable. It is only mutated for list_move_to_board, and only with lists created by the regression run.
• Temporary artifacts use a unique run id and the trello-mcp live regression ... prefix. Set TRELLO_LIVE_REGRESSION_RUN_ID when you want a human-readable run marker.
• Cleanup runs after intermediate failures. It removes tracked temporary cards, labels, attachments, member/label assignments, custom-field values, and archives temporary lists. It also searches all configured regression boards for prefix-matched lists, cards, and labels that were created before the response could be tracked.
• The suite invokes registered tool handlers with a real TrelloClient; it does not call Trello through a separate ad hoc client.
• The suite does not log API keys, tokens, credential-bearing URLs, raw environment objects, or raw request data.

Local file upload coverage is skipped by default. To include card_attachment_upload, both the normal upload root and an explicit regression test file must be configured:

TRELLO_ATTACHMENT_UPLOAD_ROOT=/absolute/path/to/trello-uploads \TRELLO_LIVE_REGRESSION_UPLOAD_FILE=sample.txt \TRELLO_LIVE_REGRESSION=1 \TRELLO_LIVE_REGRESSION_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm regression:live --domain attachments

The upload file path may be relative to TRELLO_ATTACHMENT_UPLOAD_ROOT or absolute, but it must resolve inside the upload root.

If the live env vars are absent during local validation, record the live command as skipped. The skipped state is explicit: corepack pnpm smoke:live and corepack pnpm regression:live fail before contacting Trello and print the missing variable names. Do not add either command to normal CI unless the job is intentionally secret-backed and opt-in.

GitHub Actions

The repository includes a Live Trello Smoke workflow for PR, post-merge main, and release validation. It runs on same-repository pull requests, pushes to main, and manual dispatch. Fork pull requests are skipped so Trello credentials are not exposed to untrusted PR code.

The workflow runs the offline gates (pnpm typecheck, pnpm lint, pnpm build, and pnpm test) before the secret-backed live smoke step.

Before using it, configure a GitHub Environment named live-smoke with these secrets:

Use environment required reviewers if the repository has more than one maintainer or if the token can access anything beyond the smoke board. The workflow maps those secrets to TRELLO_API_KEY and TRELLO_TOKEN only for the pnpm smoke:live step. The job sets environment.deployment: false, so the GitHub Environment still scopes secrets and protection rules without creating Deployment records. Do not use pull_request_target for this workflow.

The hosted smoke workflow is fixed to the public disposable test board short link hUaItfNq and sets TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1, so it fails before identity output or writes if Trello no longer reports that board as public. It does not accept a board override, so a maintainer cannot accidentally publish a private board's identifiers through public Actions logs or summaries. A public board is acceptable for smoke testing when temporary artifact names and activity history can be visible, but public visibility does not remove the need for Trello credentials because the harness performs writes. For another disposable board, use the local command above and keep private-board output out of public logs and artifacts.

The broader Live Trello Regression workflow is manual-only and should be used for release candidates or focused live debugging, not as an ordinary PR gate. Configure a GitHub Environment named live-regression with:

The hosted regression workflow is fixed to the public disposable primary and secondary boards hUaItfNq and r9BpowfZ and sets TRELLO_LIVE_REQUIRE_PUBLIC_BOARD=1, so it fails before identity output or writes if Trello no longer reports either board as public. It accepts optional domains and tools inputs and uploads reports/live-regression.json when the command produces it. To use different boards, run the command locally and do not publish a report for a private board. The workflow also sets environment.deployment: false because live regression is secret-backed validation, not an app deployment. Fork pull requests must not receive Trello credentials; keep live regression on workflow_dispatch or another explicitly secret-backed workflow.

The Release workflow builds the published multi-architecture Docker image for linux/amd64 and linux/arm64 on pushes to main and v*.*.* tags. It can also be run manually from a branch with push=false to perform a no-push multi-platform validation before release-image changes merge. Leave push=false for dry runs; only use push=true when intentionally publishing to GHCR.

Usage Examples

Once connected to an MCP client, ask for Trello actions in natural language:

For inspect-first multi-tool sequences with explicit proposal, approval, and verification stages, follow the workflow guide.

Show me my Trello boards.Show me the lists on my job scout board.Show me the cards in my "Today" list.Create a card called "Review invoices" in the bookkeeping list.Move this card to Done.Archive the card about the old onboarding checklist.Show the recent activity for this card.Add a comment to this card saying the invoices are ready for review.Edit this card comment to include the updated invoice total.Add this public URL as an attachment to the card.Upload the file invoice.pdf from my Trello upload folder to this card.Show me the custom fields configured on this board.Set this card's Priority custom field to the High option.Clear this card's Estimate custom field.

The exact wording depends on your MCP client. The server can discover your boards and board lists first, then use those ids for card workflows.

Large Trello Responses

Collection tools default to compact Trello reads so MCP clients do not receive unnecessarily large payloads. High-volume card, label, and action reads default to limit: 50; Trello caps these collection reads at 1000.

Use fields to request only the properties needed for a workflow. Tools that validate object names, ids, or action types automatically add schema-required fields even when you request a smaller field set. Use fields: "all" only for detailed follow-up reads where the larger response is useful.

Use since and before on card collection and action tools to page through older or newer Trello objects. These cursors accept an ISO-8601 timestamp, a Trello/Mongo id, or null where Trello supports it. Action reads also expose zero-based page for Trello's action pagination.

Use card_actions, board_actions, list_actions, and workspace_actions for bounded activity audits. Set filter: "commentCard" to focus on comments, filter: "all" for broader activity, and combine limit, since, before, and page so board, list, card, or workspace histories stay small enough for MCP clients.

Member-returning tools default to compact member fields (username,fullName,initials,avatarUrl). Use member field inputs such as fields, memberFields, or memberCreatorFields when a workflow needs additional member profile properties.

Search

Use search when a user gives a natural language term and you need to find matching cards or boards before taking action. It searches cards and boards by default, returns compact fields, and defaults to 10 results per resource type. Add members or organizations to modelTypes when member or workspace result types are useful.

Use boardIds: "mine" or specific board ids to narrow card and board search. Use organizationIds for workspace ids, plus cardIds, partial, cardsPage, and the per-type limit inputs when a query needs tighter scope or pagination. Use search_members for assignee lookup by name or username, especially when scoped by a board or workspace.

Attachment Uploads

Public URL attachments work without extra setup. Local file uploads are implemented, but they are disabled by default because the MCP client asks the server process to read a file from the server's filesystem.

To enable card_attachment_upload, set TRELLO_ATTACHMENT_UPLOAD_ROOT to an absolute directory path the server may read. Upload tool filePath values can be relative to that directory, or absolute paths that still resolve inside it. The server resolves symlinks with realpath, rejects directories, and rejects files outside the configured root before it sends any Trello request.

For local stdio use:

TRELLO_ATTACHMENT_UPLOAD_ROOT=/Users/you/trello-uploads \  TRELLO_API_KEY=your-key \  TRELLO_TOKEN=your-token \  TRANSPORT=stdio \  node dist/index.js

For Docker, mount the upload directory into the container and set the root to the container path:

docker run --rm -p 127.0.0.1:3000:3000 \  -v "$PWD/trello-uploads:/uploads:ro" \  -e TRELLO_ATTACHMENT_UPLOAD_ROOT=/uploads \  -e TRELLO_API_KEY=your-api-key \  -e TRELLO_TOKEN=your-token \  ghcr.io/enthouan/trello-mcp:latest

MCP clients do not upload bytes directly through this tool; they provide a path that must exist on the server host or inside the container. For remote servers, copy or mount the file into TRELLO_ATTACHMENT_UPLOAD_ROOT first.

Custom Fields

Custom field definitions live on Trello boards, and card values are exposed as card customFieldItems. Use board_custom_fields to discover board-level field definitions and their ids, custom_field_options to list dropdown/list options for a field, and card_custom_field_items to inspect values currently set on a card.

The write tool card_custom_field_set accepts one custom field at a time with a type-specific input shape:

Use card_custom_field_clear to clear an existing card custom field value. Trello clears custom field items with an empty PUT request shape rather than a DELETE request, so clearing is intentionally separate from setting values.

Board Creation

board_create creates a new Trello board with prefs_permissionLevel defaulting to private. Pass workspaceId to place the board in a Trello workspace/organization and set permissionLevel explicitly only when you intend workspace-visible (org) or public (public) board visibility.

API Coverage

See docs/api-coverage.md for the Trello REST API group coverage matrix, deferred endpoint families, and current non-goals.

Tool Catalog

77 tools are registered. Names, descriptions, and key inputs are generated from allTools.

Regenerate the catalog with:

corepack pnpm docs:tools

Architecture

Read How trello-mcp works for the complete request lifecycle, transport and credential boundaries, HTTP sessions, validation, rate limiting, retries, and result handling.

MCP client  -> stdio or Streamable HTTP transport  -> MCP server and tool registry  -> Trello tool handlers  -> Trello REST client  -> Trello REST API

• src/index.ts starts stdio or HTTP transport.
• src/server.ts creates the MCP server and registers tools.
• src/http-auth.ts enforces the optional MCP_AUTH_TOKEN bearer check on HTTP MCP requests.
• src/trello/auth.ts defines the read-only auth_whoami and auth_token_info credential diagnostics.
• src/trello/client.ts owns Trello HTTP requests, auth query parameters, retries, and response parsing.
• src/trello/boards.ts defines board discovery and board-level list, card, label, member, and custom field tools.
• src/trello/workspaces.ts defines workspace discovery, metadata, board, and member tools.
• src/trello/members.ts defines member profile, board, card, and workspace lookup tools.
• src/trello/lists.ts defines list create, inspect, update, archive, and move tools.
• src/trello/cards.ts defines card tools, including attachment, checklist, member, comment, action, and card custom field item helpers.
• src/trello/labels.ts defines label CRUD and card label assignment tools.
• src/trello/custom-fields.ts defines custom field definition and option lookup tools.
• src/trello/search.ts defines search tools for cards, boards, members, and workspaces.
• src/trello/fields.ts defines shared Trello field list validation helpers.
• src/trello/types.ts contains Trello response schemas.
• src/utils/* contains logging, error mapping, pagination, and tool registration helpers.

Security Notes

• Trello credentials stay in your environment or MCP client config.
• Logs redact TRELLO_API_KEY, TRELLO_TOKEN, MCP_AUTH_TOKEN, authorization headers, and common key/token fields.
• Trello API requests use HTTPS.
• Set MCP_AUTH_TOKEN for a basic shared-secret check on HTTP MCP traffic. This does not replace HTTPS, reverse-proxy authentication, IP allowlists, or careful host binding.
• Local file attachment uploads are disabled unless TRELLO_ATTACHMENT_UPLOAD_ROOT is configured; upload paths are restricted to that directory.
• Tests use mocks and injected fetchers instead of live Trello calls.
• Do not publish .env files or paste tokens into issues and PRs.

Security, Privacy, And Support

• See SECURITY.md for supported versions, vulnerability reporting, credential-handling expectations, and threat-model notes.
• See PRIVACY.md for self-hosted data handling, external services, and public issue privacy guidance.
• See SUPPORT.md for support channels, boundaries, and useful bug report context.

Development

Install dependencies:

corepack enablecorepack prepare [email protected] --activatecorepack pnpm install --frozen-lockfile

Rebuild the project from scratch:

corepack pnpm build:clean

Run the local checks:

corepack pnpm verify

Run the coverage gate:

corepack pnpm verify:coverage

Run the opt-in live Trello smoke test:

TRELLO_LIVE_SMOKE=1 \TRELLO_LIVE_SMOKE_BOARD_ID=your-disposable-board-id-or-short-link \TRELLO_API_KEY=your-api-key \TRELLO_TOKEN=your-token \corepack pnpm smoke:live

Run locally in watch mode:

TRELLO_API_KEY=your-key TRELLO_TOKEN=your-token corepack pnpm dev

Build the Docker image locally:

corepack pnpm docker:build

Codex Cloud Environments

Codex Cloud tasks run a setup script before the agent starts, and can run an optional maintenance script when a cached container resumes on a task branch. Use these repository scripts in the Codex environment settings:

./scripts/codex/setup.sh

./scripts/codex/maintenance.sh

The setup script enables Corepack, activates the pinned pnpm version, installs dependencies with --frozen-lockfile when pnpm-lock.yaml exists, and runs pnpm typecheck. The maintenance script repeats dependency sync and typecheck for cached containers so branch changes do not use stale dependencies.

Troubleshooting

Start with the complete troubleshooting guide for a boundary-by-boundary diagnosis of startup, stdio, HTTP sessions, Docker, Trello API, rate-limit, and attachment failures.

The server starts but my MCP client does not show tools

• Confirm the client is using the right transport.
• For stdio, set TRANSPORT=stdio.
• For HTTP, point the client to /mcp, not /healthz or /readyz.
• Follow the client-specific restart or reload step in the Set up your MCP client guide.

Trello says the credentials are invalid

• Run the auth_whoami and auth_token_info tools from your MCP client to confirm the authenticated member and the token's expiration and permissions.
• Confirm the token was generated from the same Power-Up/API key.
• Regenerate the token if it was revoked.

Docker Compose cannot find .env

• Copy .env.example to .env.
• Fill in TRELLO_API_KEY and TRELLO_TOKEN.
• Keep .env uncommitted.

I hit Trello rate limits

• The client uses a token-bucket limiter before each Trello request. TRELLO_RATE_LIMIT_CAPACITY controls how many requests can run in one bucket window, and TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS controls how often the bucket refills.
• When Trello returns HTTP 429, the client retries with exponential backoff. TRELLO_RETRY_MAX_ATTEMPTS controls the total request attempts, TRELLO_RETRY_BASE_DELAY_MS controls the starting delay and jitter range, and TRELLO_RETRY_MAX_DELAY_MS caps each retry wait.
• At LOG_LEVEL=debug, token-bucket waits are logged as trello rate limit wait. HTTP 429 retries are logged as trello request rate limited; retrying at warn level. These logs include safe metadata such as method, resource type, resource id, attempt, max attempts, status code, and wait duration; they do not include Trello credentials, full URLs, query strings, or raw request paths.
• First narrow the prompt or workflow: target one board or list, request only needed fields, use limit, since, before, and page where available, and avoid asking an LLM to inspect every card when a smaller search or filtered read will work.
• If large workflows still wait too often, tune cautiously. For a shared token or automation that should be gentler, lower the bucket:

TRELLO_RATE_LIMIT_CAPACITY=50TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS=10000

• For a deliberately large, user-triggered workflow, you can allow more retries without increasing the request bucket:

TRELLO_RETRY_MAX_ATTEMPTS=5TRELLO_RETRY_BASE_DELAY_MS=250TRELLO_RETRY_MAX_DELAY_MS=5000

• Avoid raising TRELLO_RATE_LIMIT_CAPACITY aggressively unless you understand the Trello account and token's real workload. Higher capacity can make a broad LLM-driven workflow hit Trello's server-side limits faster.
• Wait a few minutes before retrying a workflow after repeated 429 responses.

Contributing

PRs are welcome. Keep changes focused, add tests for behavior changes, and avoid committing secrets or local build and test output. When canonical documentation or public tool data changes, run corepack pnpm docs:tools and include the legitimate checked-in generated documentation mirrors.

Before opening a PR, run:

corepack pnpm typecheckcorepack pnpm lintcorepack pnpm buildcorepack pnpm test

License

MIT License. See LICENSE.