The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Trello MCP listing page.
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.
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.
The complete project documentation is available at trello-mcp.com:
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:
Use this path if you just want to run the server. It pulls the prebuilt image from GHCR and does not build anything locally.
Edit .env and replace the placeholder values:
Start the published image:
The default docker-compose.yml uses:
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 repeatable deployments, select a release and pin its verified index digest. See image trust and read-only verification for SBOM/provenance inspection, the GHCR signing policy, and the separate Docker-built catalog path. Metadata integrity checks do not authenticate a publisher. Published Docker image tags use these conventions:
| Tag | Use case |
|---|---|
latest | Follows the current main branch build. Use it when you intentionally want the newest main-branch image. |
X.Y | Follows the newest patch release in a minor line, moving to the image built from the latest matching vX.Y.Z tag. |
X.Y.Z | Identifies an exact release, preserved by project policy. Pin its verified digest for immutable bytes. |
sha-<commit> | Identifies a commit build; a stable release can repair this alias to its verified release digest. |
You can also run the published image directly without Compose:
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 pnpm@10.34.1 package manager through Corepack.
Edit .env with your Trello credentials, then build and run locally:
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:
Then run the compiled server directly:
Treat the token like a password. Do not commit it, paste it in logs, or share it in PRs.
Choose the transport by where the server runs:
| Your setup | Choose | Client receives |
|---|---|---|
| A built clone and the MCP client are on the same machine | stdio | A local command plus Trello credentials in the child-process environment |
| The server runs in Docker, behind a reverse proxy, or on another host | Streamable HTTP | An /mcp URL plus an optional bearer token; Trello credentials stay on the server |
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.
If you chose Streamable HTTP, check the server:
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.
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.
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.
See the configuration reference for deployment-specific applicability, secret handling, rate-limit tuning, Compose controls, and local attachment-upload requirements.
| Variable | Required | Default | Description |
|---|---|---|---|
TRELLO_API_KEY | yes | Trello API key. | |
TRELLO_TOKEN | yes | Trello token for token auth. | |
MCP_AUTH_TOKEN | no | If set, HTTP MCP requests to /mcp require Authorization: Bearer <token>. Leave unset for no HTTP bearer-token check. | |
TRELLO_ATTACHMENT_UPLOAD_ROOT | no | Absolute server-side directory that enables local file attachment uploads. Leave unset to disable local uploads. | |
TRELLO_RATE_LIMIT_CAPACITY | no | 100 | Token-bucket capacity for Trello requests before the client waits for a refill. Must be a positive integer. |
TRELLO_RATE_LIMIT_REFILL_INTERVAL_MS | no | 10000 | Token-bucket refill interval in milliseconds. Must be a positive integer. |
TRELLO_RETRY_MAX_ATTEMPTS | no | 3 | Total attempts for a Trello request when Trello returns HTTP 429. Must be a positive integer. |
TRELLO_RETRY_BASE_DELAY_MS | no | 100 | Exponential backoff base delay in milliseconds for HTTP 429 retries, with bounded jitter. Must be a positive integer. |
TRELLO_RETRY_MAX_DELAY_MS | no | 2000 | Maximum delay in milliseconds for any HTTP 429 retry wait. Must be a positive integer. |
TRANSPORT | no | http | http or stdio. |
PORT | no | 3000 | HTTP listen port for the Node process. Docker Compose keeps the container listener on 3000 and uses TRELLO_MCP_HOST_PORT for the published host port. |
LOG_LEVEL | no | info | Pino log level. |
TRELLO_MCP_HOST_BIND_IP | no | 127.0.0.1 | Docker Compose host interface bind address. Keep 127.0.0.1 for local-only access; set 0.0.0.0 to publish on all host interfaces for intentional network/LAN exposure. |
TRELLO_MCP_HOST_PORT | no | 3000 | Docker Compose host port mapped to the container's fixed internal 3000 listener. |
TRELLO_MCP_IMAGE_TAG | no | latest | Published image tag; latest follows main, X.Y follows the newest patch in that minor release line, and X.Y.Z pins to an exact release. |
TRELLO_MCP_NETWORK | no | trello-mcp_network | Docker Compose bridge network name. |
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:
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:
TRELLO_LIVE_SMOKE=1, Trello credentials, and a smoke board id or URL are all present.TrelloClient, so tool input validation, Trello response validation, retry/rate-limit handling, and credential redaction stay on the normal code path.The smoke flow validates representative v1.0 workflows:
auth_whoami, auth_token_info, list_boards, board reads, lists, cards, labels, members, memberships, and custom-field discovery.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:
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:
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.Regression safety model:
TRELLO_LIVE_REGRESSION=1, Trello credentials, and a regression board id or URL are all present.list_move_to_board, and only with lists created by the regression run.trello-mcp live regression ... prefix. Set TRELLO_LIVE_REGRESSION_RUN_ID when you want a human-readable run marker.TrelloClient; it does not call Trello through a separate ad hoc client.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:
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.
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:
| Secret | Description |
|---|---|
TRELLO_LIVE_SMOKE_API_KEY | Trello API key for a dedicated smoke-test Trello member. |
TRELLO_LIVE_SMOKE_TOKEN | Trello token for that same member, with write access to the disposable smoke board. |
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:
| Secret | Description |
|---|---|
TRELLO_LIVE_REGRESSION_API_KEY | Trello API key for a dedicated regression-test Trello member. |
TRELLO_LIVE_REGRESSION_TOKEN | Trello token for that same member, with write access to the disposable regression board. |
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.
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.
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.
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.
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.
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:
For Docker, mount the upload directory into the container and set the root to the container path:
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 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:
| Custom field type | Input shape | Notes |
|---|---|---|
text | { "type": "text", "text": "Hello" } | Plain text value. |
number | { "type": "number", "number": "42" } | Trello expects numbers as strings. |
date | { "type": "date", "date": "2026-06-03T16:00:00.000Z" } | Must be an ISO-8601 date/time string. |
checkbox | { "type": "checkbox", "checked": true } | The server sends Trello the string value Trello expects. |
list | { "type": "list", "optionId": "<custom-field-option-id>" } | Discover option ids with board_custom_fields or custom_field_options. |
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_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.
See docs/api-coverage.md for the Trello REST API group coverage matrix, deferred endpoint families, and current non-goals.
77 tools are registered. Names, descriptions, and key inputs are generated from allTools.
| Name | When to use | Key inputs |
|---|---|---|
auth_whoami | Use as a read-only credential diagnostic to confirm which Trello member the configured API key and token authenticate as. | fields |
auth_token_info | Use as a read-only credential diagnostic to inspect the configured Trello token's owner, expiration, and permissions; it does not create, refresh, revoke, or manage tokens. | fields |
list_boards | Use first when the user has not provided a board, list, card id, or Trello URL; returns boards visible to the authenticated Trello member. | filter, fields |
board_create | Use when creating a new Trello board. Creates boards as private by default, can place them in a workspace with workspaceId, and only supports explicit private, workspace, or public visibility. | name, desc, workspaceId, permissionLevel |
board_get | Use when you need board details, common board preferences, or label names for a known Trello board before listing or summarizing it. | boardId, fields |
board_field_get | Use when you need one specific board field, such as prefs, labelNames, subscribed, name, description, or URL. | boardId, field |
board_actions | Use when auditing recent activity or comments across a board; use filter, limit, page, since, before, and fields to keep large histories bounded. | boardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields |
board_lists | Use when you need the lists on a known Trello board so you can find the right list id before listing or creating cards. | boardId, filter, fields |
board_cards | Use when you need cards across all lists on a known Trello board for personal planning, review, or summarization. | boardId, filter, fields, limit, since, before |
board_custom_fields | Use when inspecting custom field definitions on a known Trello board, including dropdown/list options when Trello returns them. | boardId |
board_labels | Use when discovering labels available on a board before creating or updating cards with labels. | boardId, limit, fields |
board_members | Use when you need the members who can access a known Trello board before assigning cards or reviewing collaboration; requires token visibility of private boards. | boardId, fields |
board_memberships | Use when you need board membership records, member roles, or permission context for a known Trello board; use the admins filter when checking board-admin-only operations. | boardId, filter, member, memberFields |
list_workspaces | Use first when the user asks to show Trello workspaces or needs to choose a workspace before drilling into its boards or members. | filter, fields, paidAccount |
workspace_get | Use when you need basic Trello workspace metadata, such as display name, description, URL, website, board ids, or preferences. | workspaceId, fields |
workspace_boards | Use when you need boards in a known Trello workspace so the user can drill into a workspace board. | workspaceId, filter, fields |
workspace_members | Use when you need members in a known Trello workspace before assignment, auditing, or permission review. | workspaceId, filter, fields |
workspace_actions | Use when auditing recent activity or comments across a Trello workspace; use filter, limit, page, since, before, and fields to keep large histories bounded. | workspaceId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields |
member_get | Use after member search or board member listing to inspect a Trello member profile by id, username, or me before assignment or auditing. | memberId, fields |
member_boards | Use when you need boards associated with a known Trello member by id, username, or me; results are limited to boards visible to the configured token. | memberId, filter, fields |
member_cards | Use when you need cards assigned to a known Trello member by id, username, or me; private board cards require token access to those boards. | memberId, filter, fields, limit, since, before |
member_workspaces | Use when you need Trello workspaces associated with a known member by id, username, or me; workspace visibility and role permissions constrain results. | memberId, filter, fields, paidAccount |
list_get | Use when you need metadata for a known Trello list before creating cards in it or changing it. | listId, fields |
list_create | Use when creating a new Trello list on an existing board. | boardId, name, pos |
list_update | Use when renaming a Trello list, changing its position, or setting its archive state. | listId, name, closed, pos |
list_archive | Use when archiving or unarchiving a Trello list while keeping its cards recoverable. | listId, closed |
list_move_to_board | Move an existing list and its cards to another board, changing who can access them. Use list_update to reorder within the current board. | listId, boardId |
list_actions | Use when auditing recent activity or comments for a list; use filter, limit, page, since, before, and fields to keep large histories bounded. | listId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields |
card_get | Use when you need the current details of one Trello card by id, short link, or URL before editing or summarizing it. | cardId, fields |
card_board | Use when you need the board relationship for a known Trello card before moving, labeling, or summarizing its context. | cardId, fields |
card_list | Use when you need the current list relationship for a known Trello card before moving or reporting its status. | cardId, fields |
card_labels | Use when listing the labels currently applied to a card, including label ids for add/remove workflows. | cardId |
list_cards | Use when you need cards in a specific Trello list; use limit, since, before, and fields to keep large lists small. | listId, filter, fields, limit, since, before |
card_create | Use when the user asks to create a new Trello card in a known list; accepts title, description, due date, members, and labels. | listId, name, desc, due, pos, memberIds, labelIds |
card_update | Use when changing card metadata such as title, description, due date, due completion, or archive state without moving it. | cardId, name, desc, due, dueComplete, closed |
card_due_date_set | Use when setting, clearing, or marking completion of a card due date without changing other card metadata. Provide at least one of due or dueComplete. | cardId, due, dueComplete |
card_position_set | Use when changing only a card's position within its current list; use card_move when changing lists or boards too. | cardId, pos |
card_cover_set | Use when setting a card cover to an existing attachment id, changing cover display size, or clearing the current attachment cover. | cardId, attachmentId, size, brightness |
card_label_create_and_add | Create a new board label and apply it to this card. Use card_label_add for an existing label; repeating this creation can create duplicates. | cardId, name, color |
card_delete | Use only when the user explicitly asks to permanently delete a Trello card; archive instead for reversible removal. | cardId |
card_move | Use when moving a card to another list, another board, or a different position; this is distinct from general card metadata updates. | cardId, listId, boardId, pos |
card_archive | Use when the user wants to archive or unarchive a card while keeping it recoverable; do not use for permanent deletion. | cardId, closed |
card_attachments | Use when listing files or links attached to a card, optionally narrowed by Trello attachment fields or filter. | cardId, fields, filter |
card_attachment_get | Use when inspecting one existing card attachment by attachment id, including upload metadata when Trello returns it. | cardId, fields, attachmentId |
card_attachment_add_url | Use when attaching an existing public URL to a card; this does not upload local files. | cardId, url, name, setCover |
card_attachment_upload | Read a server-local file inside TRELLO_ATTACHMENT_UPLOAD_ROOT and transmit its contents to Trello as a new card attachment. Disabled unless that root is configured; repeated uploads can create duplicates. Use card_attachment_add_url for public links. | cardId, filePath, name, mimeType, setCover |
card_attachment_delete | Permanently delete an attachment from a card, including Trello's stored file for uploads. This cannot be undone; use card_cover_set to clear a cover without deleting its attachment. | cardId, attachmentId |
card_checklists | Use when viewing all checklists and checklist items currently on a card. | cardId |
card_checklist_create | Use when adding a new checklist to an existing card, optionally copied from another checklist. | cardId, name, sourceChecklistId |
card_checklist_update | Use when renaming a Trello card checklist or changing the checklist's position on its card. Provide at least one of name or pos. | checklistId, name, pos |
card_checklist_delete | Permanently delete a checklist and all its items from a card. This cannot be undone; use card_checklist_item_delete to remove only one item. | cardId, checklistId |
card_checklist_item_create | Use when adding a new item to an existing Trello checklist on a card. | checklistId, name, pos, checked, due, dueReminder, memberId |
card_checklist_items | Use when listing the items in one Trello checklist, including complete and incomplete items by default. | checklistId, filter, fields |
card_checklist_item_update | Use when editing a Trello card checklist item text, due date, member assignment, completion state, checklist, or position. | cardId, checkItemId, name, state, checklistId, pos, due, dueReminder, memberId |
card_checklist_item_set_checked | Use when checking or unchecking a Trello card checklist item without changing other item fields. | cardId, checkItemId, checked |
card_checklist_item_move | Use when moving a Trello checklist item to another checklist on the same card or to a different position. | cardId, checkItemId, checklistId, pos |
card_checklist_item_delete | Permanently delete one checklist item. This cannot be undone; use card_checklist_item_set_checked to mark completion while keeping the item. | cardId, checkItemId |
card_custom_field_items | Use when reading all custom field item values currently set on a Trello card. | cardId |
card_custom_field_set | Set or replace one card custom field value, using the existing definition's type from custom_field_get. Use custom_field_options to find list option ids and card_custom_field_clear to remove a value. | cardId, customFieldId, type, text, number, date, checked, optionId |
card_custom_field_clear | Clear one card's custom field value without deleting the board's field definition. Restoring it requires setting the previous value with card_custom_field_set. | cardId, customFieldId |
card_members | Use when listing members assigned to a card; requires token access to the card's board. Use fields to keep member output small. | cardId, fields |
card_member_add | Use when assigning a Trello member to a card by member id; requires write access to the card's board and a member who can be assigned to that board. | cardId, memberId |
card_member_remove | Use when unassigning a Trello member from a card by member id; requires write access to the card's board. | cardId, memberId |
card_comment_add | Add a new comment to a Trello card and return its comment action. Repeating the call creates another comment; use card_comment_update to edit an existing comment. | cardId, text |
card_comment_update | Use when editing the text of an existing Trello card comment by its comment action id. | actionId, text |
card_comment_delete | Permanently delete a card comment by its action id. This cannot be undone; use card_comment_update to edit the text instead. | actionId |
card_actions | Use when auditing recent activity or comments for a card; use filter, limit, page, since, before, and fields to page large histories. | cardId, filter, fields, limit, since, before, page, member, memberFields, memberCreator, memberCreatorFields |
label_get | Use when you need the current name, color, or board for a specific Trello label before editing it. | labelId |
label_create | Use when creating a new reusable label on a Trello board before applying it to cards. | boardId, name, color |
label_update | Use when renaming a Trello label or changing its color without changing any card assignments. | labelId, name, color |
label_delete | Use only when explicitly asked to permanently delete a board label, removing it from every card using it. Use card_label_remove to unassign it from just one card while preserving the label. | labelId |
card_label_add | Use when applying an existing Trello label to a card by label id. | cardId, labelId |
card_label_remove | Use when removing an existing Trello label from a card by label id. | cardId, labelId |
custom_field_get | Use when you need one Trello custom field definition by id, including its type and any dropdown/list options Trello returns. | customFieldId |
custom_field_options | Use when listing the available options for a Trello dropdown/list custom field before setting a card list custom field value. | customFieldId |
search | Search Trello and return grouped cards, boards, members, and workspaces visible to the token. Defaults to cards and boards; scope and limit results, and use cardsPage for card pagination. Use search_members for a focused member lookup. | query, modelTypes, boardIds, organizationIds, cardIds, cardFields, boardFields, memberFields, organizationFields, cardsLimit, boardsLimit, membersLimit, organizationsLimit, cardsPage, partial, includeCardBoard, includeCardList, includeCardMembers, includeBoardOrganization |
search_members | Use when looking up Trello members by name or username, optionally scoped to a board or workspace; scoped searches require token access to that board or workspace. | query, limit, boardId, organizationId, onlyOrgMembers |
Regenerate the catalog with:
Read How trello-mcp works for the complete request lifecycle, transport and credential boundaries, HTTP sessions, validation, rate limiting, retries, and result handling.
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.TRELLO_API_KEY, TRELLO_TOKEN, MCP_AUTH_TOKEN, authorization headers, and common key/token fields.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.TRELLO_ATTACHMENT_UPLOAD_ROOT is configured; upload paths are restricted to that directory..env files or paste tokens into issues and PRs.Install dependencies:
Rebuild the project from scratch:
Run the local checks:
Run the coverage gate:
Run the opt-in live Trello smoke test:
Run locally in watch mode:
Build the Docker image locally:
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:
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.
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.
TRANSPORT=stdio./mcp, not /healthz or /readyz.auth_whoami and auth_token_info tools from your MCP client to confirm the authenticated member and the token's expiration and permissions..env.env.example to .env.TRELLO_API_KEY and TRELLO_TOKEN..env uncommitted.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.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.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.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.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.429 responses.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:
MIT License. See LICENSE.