Skip to main content
Glama
AxGrid

trello-mcp

by AxGrid
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

trello-mcp

A small MCP server for Trello, built around the one thing the popular Trello MCP servers don't do: searching cards by custom field (e.g. find every card where the AI Ready field equals Claude kiosk).

It talks to the Trello REST API directly using your API key + token, returns compact results (no multi-hundred-KB board dumps), and resolves boards/cards by id, 8-char shortLink, URL, or name.

Tools

Tool

What it does

list_boards

All boards you can access — {id, name, shortLink, url}, nothing else.

list_custom_fields

Custom fields on a board + the allowed options for list-type fields. Use it to discover field names/values.

find_cards

Main tool. Find cards on a board, filtered by a custom field (fieldName + value, or values to match ANY of several), and/or listName, and/or label. Matching is case-insensitive (exact first, then substring). Omit value(s) to match "field is set".

get_card

Full content of one card: description, custom field values, checklists, attachments, comments, members, due date.

add_comment

Post a comment to a card (ask a clarifying question, or log progress).

set_custom_field

Set/clear a custom field on a card; createOption:true adds a new list option. Used to mark status (e.g. AI Ready → Done).

attach_file

Attach a file to a card — a local file by path or a remote file by url. Handy for posting a result file when finishing a task.

Related MCP server: Trello MCP Server

Setup

1. Get Trello credentials

Create a Power-Up at https://trello.com/power-ups/admin, grab the API Key from its API Key tab, then generate a Token:

https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&name=trello-mcp&key=YOUR_API_KEY

The Power-Up Secret is for OAuth and is NOT used here — only API Key + Token.

2. Register with Claude Code — zero clone, straight from GitHub

claude mcp add trello-cf --scope user \
  -e TRELLO_API_KEY=YOUR_KEY \
  -e TRELLO_TOKEN=YOUR_TOKEN \
  -- npx -y github:AxGrid/trello-mcp

--scope user makes it available in every project. npx installs and runs it on first launch — no git clone, no npm install. Restart Claude Code afterwards.

Or in claude_desktop_config.json / any MCP client:

{
  "mcpServers": {
    "trello-cf": {
      "command": "npx",
      "args": ["-y", "github:AxGrid/trello-mcp"],
      "env": { "TRELLO_API_KEY": "YOUR_KEY", "TRELLO_TOKEN": "YOUR_TOKEN" }
    }
  }
}

npx caches the GitHub package per resolved commit. To force a pull of the latest main, clear it once: npx clear-npx-cache (or rm -rf ~/.npm/_npx).

Local / dev install

git clone git@github.com:AxGrid/trello-mcp.git && cd trello-mcp && npm install
# then point the client at: node /abs/path/to/trello-mcp/server.mjs

Example

Find cards on the Stellar Kiosk board where AI Ready = Claude kiosk and let's solve them.

Claude calls find_cards({ board: "Stellar Kiosk", fieldName: "AI Ready", value: "Claude kiosk" }), then get_card(...) on the match.

Task lifecycle via a custom field

A single list-type field (here AI Ready) doubles as a status. Suggested values:

State

Value

How

Queued for AI

Claude kiosk, Claude Module, …

pick up with find_cards({fieldName:"AI Ready", values:["Claude kiosk","Claude Module"]})

Needs a human answer

Need response

set_custom_field(card, "AI Ready", "Need response", createOption:true) + add_comment(card, "question…")

Done

Done

optionally attach_file(card, path:"…/result.…"), then set_custom_field(card, "AI Ready", "Done", createOption:true)

Setting a new state moves the card out of the "queued" search automatically, since the field no longer equals a queued value. createOption:true is only needed the first time a value is introduced.

Self-test

Runs the core logic against your real account (read-only):

TRELLO_API_KEY=... TRELLO_TOKEN=... TEST_BOARD="Your Board" node selftest.mjs

Requirements

Node 18+ (uses the built-in global fetch). The only runtime dependency is @modelcontextprotocol/sdk.

Available Tools

6 tools
add_commentA

Post a comment to a card (useful for asking a clarifying question or logging progress while solving a task).

ParametersJSON Schema
NameRequiredDescriptionDefault
cardYesCard id, shortLink, or URL.
textYesComment body (Markdown supported).

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Post a comment', indicating a write operation, but lacks details on permissions, side effects (e.g., updates timestamps), or any restrictions. This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the purpose and typical use cases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 2 required parameters and no output schema or annotations. The description covers the action and typical use cases, but does not mention return values or confirmation. For a simple comment-posting action, this is largely adequate, though slight improvement could mention success indication.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (card and text), so the schema already fully documents them. The description adds no additional semantic meaning beyond the schema, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Post a comment to a card' with specific verb and resource, and adds context 'useful for asking a clarifying question or logging progress while solving a task'. This effectively distinguishes it from sibling tools like find_cards, get_card, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit use cases ('asking a clarifying question or logging progress'), giving clear context on when to use. However, it does not explicitly mention when not to use or suggest alternatives, but the guidance is sufficient for a focused tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_cardsA

Find cards on a board, optionally filtered by a custom field value, list name, and/or label. This is the main tool: e.g. fieldName='AI Ready', value='Claude kiosk'. Use values to match ANY of several values at once, e.g. ['Claude kiosk','Claude Module'] to pull the whole queue, or ['Need response'] to see what's waiting on a human. Matching is case-insensitive (exact first, then substring). Omit value/values to match cards where the field is simply set.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYesBoard id, shortLink, URL, or unique name.
labelNoOptional: only cards with this label name or color.
valueNoA single desired value of the custom field, e.g. 'Claude kiosk'.
valuesNoSeveral values; a card matches if it has ANY of them (combined with `value`).
listNameNoOptional: only cards whose list name contains this.
fieldNameNoCustom field name to filter by, e.g. 'AI Ready'.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses case-insensitive matching, exact then substring priority, and behavior when value/values are omitted. Lacks information on pagination, rate limits, or permissions, but for a search tool this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise and front-loaded: the first sentence states purpose. No unnecessary words. Every sentence adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description should mention what is returned (e.g., list of card objects). It does not specify return format, which is a gap for a tool that finds multiple cards.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value by explaining the logic of 'values' (ANY matching), omission of value/values meaning field is set, and case-insensitivity. This goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds cards on a board with optional filters, and positions itself as 'the main tool'. It distinguishes well from sibling tools like get_card (single card) and set_custom_field (single field update).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides examples of when to use value vs values, and explains matching behavior. However, it does not explicitly state when to use alternatives like get_card or list_custom_fields.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_cardA

Get the full content of one card: description, custom field values, checklists, attachments, comments, members, due date.

ParametersJSON Schema
NameRequiredDescriptionDefault
cardYesCard id, 8-char shortLink, or card URL.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It indicates a read operation by listing returned items, but does not explicitly state read-only nature, authentication needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the purpose and includes a clear list of contents, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with one parameter and no output schema, the description is largely complete, though it could explicitly state read-only behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines the parameter. The description adds no extra parameter information beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'full content of one card', listing specific items included. It effectively distinguishes from sibling tools like add_comment and find_cards.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving card details but provides no explicit guidance on when to use this tool versus alternatives like find_cards, nor does it state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_boardsA

List all Trello boards you can access. Returns compact {id, name, shortLink, url} — use this instead of dumping full board JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It discloses it's a read-only list operation and mentions the compact output, but does not address authentication, rate limits, or pagination. Adequate but could be more explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no unnecessary words. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description covers purpose and output structure. It does not clarify permissions or access scope, but overall is fairly complete for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so schema coverage is 100%. The description adds value by specifying the output fields, which is helpful since there is no output schema. Baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List all Trello boards you can access') and specifies the output format (compact {id, name, shortLink, url}). It distinguishes from sibling tools by noting this is a lightweight alternative to full board JSON, though siblings are different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some context ('use this instead of dumping full board JSON') but does not explicitly state when to use this tool versus siblings like find_cards or get_card. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_custom_fieldsA

List the custom fields defined on a board, including the allowed options for list-type fields. Use this to discover field names and values before calling find_cards.

ParametersJSON Schema
NameRequiredDescriptionDefault
boardYesBoard id, 8-char shortLink, board URL, or (unique) name.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses that list-type fields include allowed options, but does not mention permissions, whether all fields are returned, or any side effects. For a simple read operation, this is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words. Front-loaded with the action 'List the custom fields' and immediately gives usage guidance. Excellent conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose and usage context well. Given the tool's simplicity (one parameter, no output schema, no annotations), it is nearly complete. Could mention the return format or field count, but not necessary for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single board parameter, which already describes valid formats (id, shortLink, URL, name). The description adds no additional parameter meaning, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists custom fields on a board and explains its purpose as a prerequisite for find_cards, differentiating it from sibling tools like find_cards or set_custom_field.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use this before find_cards to discover field names and values. It implies usage context but does not explicitly state when not to use or provide alternatives for other tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_custom_fieldA

Set (or clear) a custom field on a card — e.g. mark a task done by setting AI Ready to 'Done'. For list-type fields the value is matched to an existing option; pass createOption:true to add a new option. Leave value empty to clear the field.

ParametersJSON Schema
NameRequiredDescriptionDefault
cardYesCard id, shortLink, or URL.
fieldYesCustom field name, e.g. 'AI Ready'.
valueNoValue to set. Empty/omitted clears the field.
createOptionNoFor list fields: create the option if it doesn't exist yet (default false).

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses set/clear and list-field matching behavior, but lacks details on idempotency, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, efficient and front-loaded with action and example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main behaviors for all parameters; no output schema, so return value not needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds value beyond schema by explaining clear behavior and createOption usage; schema already covers parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it sets or clears a custom field on a card, with an example. Distinct from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes parameter usage for list fields and clearing, but no explicit guidance on when to use this tool vs siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct operation: adding comments, searching cards, fetching card details, listing boards, listing custom fields, and setting custom fields. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., add_comment, find_cards, list_boards), making them predictable and easy to distinguish.

Tool Count5/5

With 6 tools, the server covers the essential operations for interacting with Trello boards and cards without being excessive or insufficient.

Completeness4/5

The set covers common workflows like searching, reading, and updating cards, and listing boards and custom fields. However, it lacks create_card and delete_card, which are basic CRUD operations.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AxGrid/trello-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server