Security and access policy

Workspace allowlist and object ownership

TRELLO_ALLOWED_WORKSPACES accepts comma-separated workspace ids or canonical names, not display names. Unset means unrestricted within your token's permissions. This is additional server policy, not a replacement for token permissions.

• Every scoped read and write resolves the actual owning board. A supplied boardId is a constraint, never authorization.
• Moves and copies check source and destination. Comments, checklist items, attachments, labels, custom fields and member references are verified against their actual parents before mutation.
• Unverifiable ownership fails closed. Ownership grants are not cached across calls, so moved boards are rechecked.
• Allowlist denials name selectors and caller-supplied ids only; a boardId mismatch on an allowed object names its board.

Trello has no atomic authorization-and-mutation API, so local checks cannot prevent concurrent upstream moves between verification and mutation.

Writes are enabled by default; read-only is opt-in

"/absolute/path/to/trello-mcp" auth --read-only

Use the absolute path the installer printed. In Claude Desktop, create the token with scope=read for read-only access at Trello; the extension's read-only setting only hides write tools in this server.

Alternatively set TRELLO_READ_ONLY=1 in the server's environment. It hides all 29 mutation and transfer tools, including downloads that write local files. The 19 reads and local-selection tools remain eligible, subject to your tool profile.

A saved scope=read token implies read-only mode even with TRELLO_READ_ONLY=0. workspace_use and board_use still change local defaults. TRELLO_TOOLS selects comma-separated tool names or prefix groups; unknown selectors fail startup. The ten-tool read-oriented profile is in the setup guide.

Discover the effective access policy

MCP initialization instructions carry a compact policy summary and point to policy health. If a tool is hidden or an operation is refused, call server_health with:

{"detail":"policy"}

Health is local configuration, not validated Trello authentication. Basic/detailed report credentialSource as env, file or none, and configured responses include access: "unverified; call workspace_find". Metadata and policy exist only with credentials; unconfigured details return the setup response. Use workspace_find {} for a real Trello read. Empty success proves the read worked, not that a workspace selector matches. A permitted board_find can serve profiles without workspace_find; health-only profiles cannot verify access. Change the profile/reconnect if appropriate, never bypass restrictions. Desktop users need no CLI auth/status; CLI status describes that invocation, not Desktop credentials. Policy labels are best effort, not auth validation.

Policy health reports the allowlist, read-only state, credential scope, tool profile, enabled tool count, hidden write tools and the upload and download settings. Policy denials say they are server policy, not a token error. Upstream failures use trello API: HTTP <status>; a configured 401 or 403 is a token or permission issue, never missing setup. Without credentials, only server_health is registered, with a hint to run the installer's absolute-path auth command or fill in Desktop extension settings.

Saved credentials

The default file is ~/.secrets/.trello-mcp.secret (%USERPROFILE%\.secrets\.trello-mcp.secret on Windows). MCP client configurations need only the executable path. Precedence is the complete environment pair, then an absolute TRELLO_MCP_CREDENTIALS file, then the default file, then the shared ~/.secrets.env.

• Auth creates missing directories as 0700 and files as 0600 on Unix, or protected owner-only ACLs on Windows, and repairs a safe current-user-owned default ~/.secrets to 0700.
• Symlinks, foreign owners, group or world accessible files and unsafe directories are refused rather than bypassed. Custom parent directories are never changed.
• The file is plaintext; protect backups. The authorization link contains your API key, so keep it private.
• Logout removes the saved keys but does not revoke the token at Trello.

The macOS and Windows amd64 Desktop extension uses OS secure storage, passing sensitive settings as environment variables. Linux Desktop is beta; secure storage is unverified. Updates are manual: verify the checksum, install, check settings, restart, verify access. Settings may not be retained. Remove/disable in Settings > Extensions, manage retained sensitive settings using supported controls and revoke Trello access separately. Uninstall promises no secure-storage deletion or revocation. CLI logout is not Desktop cleanup; never inspect/delete keychains or credential stores. The authorization template requests read/write for 30 days; renewal is human-only in browser/settings. Read-only and allowlist settings restrict this server, not token authority; use scope=read for read-only Trello access.

The storage format, permission rules, exact error messages with safe fixes, locking and manual setup are in the configuration reference.

Attachment uploads and downloads

Local path uploads are disabled until TRELLO_UPLOAD_DIR names an absolute, dedicated staging directory; only regular files inside it may be uploaded and symlinks are refused. Base64 uploads need fileName. Downloads go to a private directory (TRELLO_DOWNLOAD_DIR, default under the temporary directory), verify card ownership and attachment membership, refuse redirects and never overwrite files. Both directions are capped at 10 MiB and results never include inline file bodies.

Local path uploads and attachment downloads fail closed on Windows even with directories set; configuring directories cannot enable them. Base64 uploads and URL attachments remain alternatives subject to write/profile policy; the URL is passed to Trello, not fetched locally. Read-only mode hides every attachment transfer but keeps metadata discovery.

Defensive HTTP and response handling

Requests have deadlines, redirects are refused, credentials are scrubbed from errors and upstream error bodies are not returned. JSON responses are capped at 8 MiB. Results are compact text-only JSON. Rate limits and retries are bounded per process, but other clients sharing your credentials consume the same quota. After an ambiguous write failure do not repeat the operation blindly: it may already have succeeded.

See the tool reference and the setup guide.