trello-ops-mcp
Provides read-only operational facts about Trello boards, including board discovery, list history, card movement analytics, workflow flow metrics, staleness signals, and due-date information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@trello-ops-mcp How many cards moved from To Do to Done in the past week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
trello-ops-mcp
A local, read-only Model Context Protocol server that gives LLM agents (Claude and others) deterministic operational facts about Trello boards — structural history, card movement, workflow flow, staleness, and due dates.
It never writes to Trello. It has no mutation endpoints, no write tools, and no way to change board state, even accidentally.
Overview
Trello boards accumulate a lot of operational history that's hard to see from the UI alone: who renamed a list and when, how many cards moved between stages this week, which cards have gone quiet, what's overdue. trello-ops-mcp exposes that history to an MCP-capable agent as a set of small, composable tools — each one answers a narrow, factual question, and each one is deterministic: same input, same output, every time.
The server deliberately stops at facts. It does not decide whether a list is a "bottleneck," whether a card is "blocked," or whether a person is "productive" — those are judgment calls that need context the server doesn't have, so they're left to the agent reasoning over the data. See Design philosophy.
Related MCP server: trello-mcp
Why this exists
Trello already contains most of the operational data a team would want to reason about — who did what, when, and how cards flow through a board. But that data is spread across paginated REST endpoints with inconsistent shapes, and an LLM agent asked to "check the board" has no reliable way to fetch, filter, and combine it correctly on its own, every time it's asked.
This MCP server does that translation once, consistently: it turns raw Trello API responses into small, deterministic, structured operational signals — movement counts, flow numbers, staleness thresholds, due-date facts — that an agent can call directly and compose into an answer, instead of re-deriving the same parsing and pagination logic every time.
Features
Read-only MCP tools across board discovery, structural audit (list history), movement/flow analytics, and due-date/staleness signals.
Board references in any form — internal ID, shortLink, or full board URL, normalized in one place.
Bounded, paginated Trello Actions scanning with an explicit
truncatedflag — never a silent partial result.A pure, fixed-clock-tested domain layer for every analytic computation (movement counts, list flow, overdue/upcoming/stale classification) — no HTTP, no side effects, fully unit-testable.
Credential-safe by construction — env-var-only credentials, lazy validation (tools that don't need Trello still work without them), and error messages that are structurally incapable of leaking a key or token.
Zero write surface — the Trello client only ever issues
GETrequests. There is no code path that can call a mutating Trello endpoint.
Installation
Requires Node.js >= 18.
git clone https://github.com/YOUR_GITHUB_USERNAME/trello-ops-mcp.git
cd trello-ops-mcp
npm installQuick Start
git clone https://github.com/YOUR_GITHUB_USERNAME/trello-ops-mcp.git
cd trello-ops-mcp
npm install
cp .env.example .env # then fill in TRELLO_API_KEY and TRELLO_TOKEN — see Configuration
npm run build
npx @modelcontextprotocol/inspector node dist/index.jsThat last command opens a browser UI where you can call any tool directly and see the response — the fastest way to confirm everything is wired up before connecting a real agent. To use it from Claude Desktop instead, see Connecting to Claude Desktop.
Configuration
Variable | Required for | Notes |
| All tools except | From trello.com/app-key |
| All tools except | Generate with read-only scope (see below) |
| — |
|
Getting Trello credentials:
Go to trello.com/app-key while logged into the Trello account you want to audit. Copy the API Key.
On the same page, click the Token link to generate a personal token. When prompted for scope, choose read-only. This isn't just a formality — it means that even if this server had a bug, the credential itself physically cannot modify your boards.
Put both values in
.env(copy.env.exampleas a starting point):TRELLO_API_KEY=your_api_key_here TRELLO_TOKEN=your_read_only_token_here
Credentials are validated lazily, only when a Trello-backed tool actually runs — so the server starts and health_check works even with no .env at all. Never commit your .env file; it's already excluded via .gitignore.
Connecting to Claude Desktop
Build the server first — Claude Desktop launches the compiled output, not the TypeScript source:
npm run buildOpen Claude Desktop's config file:
OS
Location
macOS
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows
%APPDATA%\Claude\claude_desktop_config.jsonLinux (community builds)
~/.config/Claude/claude_desktop_config.jsonAdd an entry under
mcpServers, using the absolute path to your clone:{ "mcpServers": { "trello-ops-mcp": { "command": "node", "args": ["/absolute/path/to/trello-ops-mcp/dist/index.js"], "env": { "TRELLO_API_KEY": "your_api_key_here", "TRELLO_TOKEN": "your_read_only_token_here" } } } }Restart Claude Desktop completely (quit, not just close the window). A new MCP tool icon should appear in the chat input, and
trello-ops-mcp's tools should be listed there.
Common mistakes:
Relative path in
args. Claude Desktop doesn't run from your project directory — it needs the full absolute path todist/index.js.Forgetting to build. If
dist/index.jsdoesn't exist yet, Claude Desktop will fail to launch the server silently. Runnpm run buildfirst, and re-run it after pulling new changes.Trailing commas or comments in the JSON config. Standard JSON doesn't allow either — a config that "looks right" but has one extra comma will fail to parse.
Editing the config while Claude Desktop is running. Config changes only take effect after a full restart.
Env vars set in your shell but not in the config's
envblock. Claude Desktop launches the server as its own process — it doesn't inherit your terminal's environment. Credentials must go in theenvblock shown above.
Troubleshooting:
Test the server manually first, outside Claude Desktop:
node dist/index.jsshould printtrello-ops-mcp server startedto stderr and then sit waiting for stdio input (Ctrl+C to exit). If that fails, fix it before involving Claude Desktop at all.Check Claude Desktop's own MCP logs (accessible from its developer/settings menu on most platforms) for the specific startup error.
Call
health_checkfirst from within Claude. It needs no credentials, so if it fails, the problem is the server process/config, not your Trello token.If
health_checkworks but every other tool fails, the problem is almost always the credentials in theenvblock — re-check them against Configuration.
Using MCP Inspector
MCP Inspector drives the server over stdio from a browser UI — useful for testing tools directly without a full agent in the loop.
npm run build
npx @modelcontextprotocol/inspector node dist/index.jsIn the UI: pick a tool from the list, fill in its inputs (e.g. board — accepts an ID, shortLink, or full URL), and run it. You'll see both the structured JSON result and the human-readable text summary the tool also returns.
Architecture
Trello REST API
│
▼
Trello Client src/trello — typed, read-only HTTP wrapper (auth, pagination, error mapping)
│
▼
Pure Domain Analytics src/domain — deterministic classifiers & analytics, zero HTTP/MCP imports
│
▼
MCP Tools src/tools — validates input, orchestrates client + domain, formats output
│
▼
LLM Agent (Claude, or any MCP-capable client)Each layer only talks to the one directly below it. In particular, the domain layer never imports the Trello client — every domain function is pure (data in, data out), which is what makes it possible to unit-test all the analytics logic with fixtures and a fixed clock, with no network and no MCP mocking. A tool is the only place these two layers meet: it fetches raw data from the Trello client, hands it to a domain function, and formats the result.
get_list_flow → trello.getBoardActions() → classifyCardMovements() + computeListFlow() → MCP responseDesign philosophy: facts, not conclusions
The MCP layer computes and returns facts — movement counts, flow numbers, staleness thresholds, due-date math. It deliberately does not compute a board health score, classify a list as a "bottleneck," decide a card is "blocked," or judge whether someone is "productive." Concretely:
No
board_insights,board_risks,what_needs_attention,detect_bottleneck, orrecommend_actionstools exist, and none are planned.get_list_flowreportsincomingMoves/outgoingMoves/netFlowper list — never a "bottleneck" label. A list withnetFlow: +17is a fact; whether that's a problem depends on context the server doesn't have.get_stale_cardsreports cards with no recognized recent activity — never "blocked." A quiet card might be low priority, waiting on something external, or genuinely forgotten — Trello data alone can't tell those apart.cardsMoved(get_card_movements/get_top_card_movers) measures workflow activity, not productivity or performance — a card can be moved by someone other than whoever did the underlying work.
An agent can combine these facts into a real answer (e.g. cross-referencing get_stale_cards with get_overdue_cards), but that interpretation happens in the agent's reasoning, not inside this server.
Available MCP Tools
board accepts a Trello internal board ID, a shortLink, or a full board URL. since/before accept ISO 8601 timestamps. Every historical tool bounds its Trello Actions scan via maxActions (default 1000) and reports truncated: true rather than silently dropping data if the cap is hit.
Discovery
Tool | Input | Returns |
| — | Server status. No credentials required. |
| — | Boards accessible to the configured account. |
|
| Lists on a board. |
|
| Members on a board. |
|
| Raw cards on a board. |
Structural audit
Tool | Input | Returns |
|
| Low-level, compact view of raw board action history. |
|
| Who created/renamed/archived/unarchived lists, with |
Movement & flow analytics
Tool | Input | Returns |
|
| Confirmed list-to-list card movements, optionally filtered. |
|
| Members ranked by movement count (default: last 7 days). |
|
| Incoming/outgoing/net movement counts per list (default: last 7 days). |
|
| One member's chronological activity feed. |
Due-date & staleness signals
Tool | Input | Returns |
|
| Cards past due, incomplete, not archived (current state). |
|
| Cards due within N days, default 7 (current state). |
|
| Open cards with no recognized activity for N days, default 14. |
Due-date tools read the board's current card state (always complete, always current). Movement/flow/staleness/member tools read Trello's Actions history, which is bounded by maxActions and by however far back Trello itself retains action data — see truncated in each tool's output.
Example interactions
Walkthrough: "What should I review today?"
There is no what_should_i_review tool, and there never will be — this question is exactly the kind of subjective synthesis this server leaves to the agent. Here's what actually happens:
User asks: "What should I review today?"
The agent decides which facts it needs and picks tools accordingly — in this case, three:
get_overdue_cards— cards already past dueget_upcoming_due_cards— cards due soonget_stale_cards— cards with no recent recognized activity
The MCP returns three sets of facts — card IDs, names, dates, thresholds — with no ranking, prioritization, or commentary attached.
The agent reasons over the combined results (e.g. noticing a card that's both overdue and stale) and only then produces a natural-language answer.
Every answer this server participates in takes this shape: user question → agent chooses tools → MCP returns operational signals → agent reasons over them → natural-language answer. Step 3 is where this server's job ends.
"Who moved the most cards this month?"
→ Agent calls get_top_card_movers with days: 30, then reports the ranked list with each member's cardsMoved count.
"What cards haven't moved recently?"
→ Agent calls get_stale_cards (default 14-day threshold), noting which results have historyComplete: false (uncertain) versus true (confirmed).
"Show overdue work."
→ Agent calls get_overdue_cards, presenting cards sorted most-overdue-first with daysOverdue for each.
"Which lists received the most work this week?"
→ Agent calls get_list_flow with days: 7 (or no days at all — that's the default), and reads off the lists with the highest incomingMoves.
"Are there overdue cards that also look inactive?"
→ Agent calls both get_overdue_cards and get_stale_cards, then intersects the results by cardId — a piece of reasoning this server deliberately leaves to the agent rather than doing itself.
Screenshots
Screenshots demonstrating the MCP Inspector and Claude Desktop integration will be added in a future release.
Security
Read-only by construction, not just by convention.
src/trello/client.tsis the only code in the project that makes HTTP calls to Trello, and every one of its methods issues aGETrequest. There is no method, no code path, and no tool that can call a mutating Trello endpoint.Credentials never leave the environment.
TRELLO_API_KEY/TRELLO_TOKENare read from.env(viadotenv) or the process environment — never hardcoded, never committed (.gitignoreexcludes.env), and validated lazily so tools that don't need Trello still work without them.No credential logging, ever. The logger writes only to stderr for operational messages (server start, log level) and never touches request data. Trello API errors are deliberately shaped to include only the HTTP status, the request path (never the query string, which is where the key/token live), and Trello's own error message — verified by dedicated tests.
A read-only-scoped Trello token is still recommended. Even though this server's code can't issue a write, a read-only token means a compromised environment or a future bug still can't touch your boards.
Action history is bounded, and truncation is never silent. Every tool that scans Trello's Actions API reports
truncated: truewhen it stops early due tomaxActions, andget_stale_cardsexplicitly marks a cardhistoryComplete: falserather than asserting confidence it doesn't have.
If you find a security issue, please open an issue on the repository rather than a public discussion of the specifics.
Development
npm run dev # run directly from TypeScript source (tsx), no build step
npm run build # compile to dist/
npm start # run the compiled server (dist/index.js)
npm run typecheck # type-check without emitting output
npm test # run the test suiteProject layout:
src/
index.ts # server bootstrap, stdio transport
config/ # env loading (general config + lazy Trello credentials), version
trello/ # Trello API client: HTTP, auth, board-ref normalization, errors, types
domain/ # pure classifiers/analytics: events, movements, flow, staleness, due dates
tools/ # MCP tool definitions, one file per feature area
utils/ # logger, centralized date-range validation
tests/
tools/ # tool-layer tests (mocked Trello client, real in-memory MCP transport)
trello/ # Trello client tests (board-ref normalization, pagination, mocked fetch)
domain/ # domain logic tests (fixture-based, fixed-clock, no network)
utils/ # date validation/resolution tests
fixtures/ # sanitized Trello payloads modeled on real captured shapesThe tools/domain/client separation is enforced by convention, not tooling — when adding to this codebase, keep domain functions free of HTTP/MCP imports, and keep Trello-shape-specific parsing inside src/trello/.
Testing
npm testA focused, high-value behavioral test suite — intentionally kept small rather than exhaustive (coverage percentage is not a goal here). The suite is fully offline — no test ever calls the real Trello API:
Domain tests exercise pure classifiers and analytics against fixture data (modeled on real Trello payloads captured during development, then sanitized) and, where time matters, a fixed injected clock.
Trello client tests mock
fetchto verify auth/query construction, HTTP and rate-limit error mapping, and Actions pagination/truncation behavior.Tool tests mock the Trello client and drive real
McpServer/Clientinstances over an in-memory transport, proving the MCP wiring (validation, orchestration, structured output, safe error formatting) end-to-end for a representative tool from each category.
Roadmap
Ideas under consideration for future versions. None of these are committed, scheduled, or promised on any timeline — this is a list of directions, not a plan.
Remote MCP transport (currently stdio-only, by design, for v0.1)
SQLite cache for faster repeat queries on large boards
Webhook ingestion as an alternative to polling Trello's Actions API
Cross-board analytics (currently every tool is scoped to one board)
Historical snapshots for tracking board state over time, not just recent actions
Trend analysis (week-over-week movement/flow comparisons)
Agent-generated reporting — explicitly on the agent side of the boundary described in Design philosophy, not inside this server
License
Available Tools
14 toolsget_board_actionsGet Board ActionsA
Low-level historical inspection/debug tool: returns a compact, normalized view of a board's raw action history. For structural list-change auditing, prefer get_list_changes.
Inputs: board (required), since, before, maxActions, +1 more. Returns: actions, truncated, actionsScanned, requestedRange
get_board_cardsGet Board CardsA
Get the cards on a Trello board, identified by ID, shortLink, or board URL. Returns raw card data (list, members, due date) — no overdue/analytics computation.
Inputs: board (required), includeClosed. Returns: cards
get_board_listsGet Board ListsA
Get the lists on a Trello board, identified by ID, shortLink, or board URL.
Inputs: board (required), includeClosed. Returns: lists
get_board_membersGet Board MembersA
Get the members on a Trello board, identified by ID, shortLink, or board URL.
Inputs: board (required). Returns: members
get_boardsGet BoardsA
Get the Trello boards accessible to the configured account.
Inputs: no named parameters. Returns: boards
get_card_movementsGet Card MovementsA
List confirmed list-to-list card movements from a board's action history, optionally filtered by member, card, source list, or destination list. Workflow activity, not a productivity metric.
Inputs: board (required), since, before, cardId, +4 more. Returns: movements, truncated, actionsScanned, requestedRange, +1 more
get_list_changesGet List ChangesA
Main structural audit tool: who created, renamed, archived, or unarchived lists on a board, optionally scoped to a date range and/or a single list.
Inputs: board (required), since, before, listId, +1 more. Returns: events, truncated, matchedEvents, actionsScanned, +1 more
get_list_flowGet List FlowA
Returns incoming and outgoing card movement counts by Trello list for a date range (explicit since/before, or the convenience days — default last 7 days if neither is given). Useful for seeing where card movement concentrates. This is a factual movement-flow signal only — it does not identify bottlenecks, throughput, or performance; that interpretation is left to the caller.
Inputs: board (required), days, since, before, +1 more. Returns: flow, truncated, actionsScanned, requestedRange, +1 more
get_member_activityGet Member ActivityA
Normalized chronological activity feed for one board member: card movements, list structural changes, card creation, and card archival. Resolve by memberId when known; memberName is looked up against board members and rejected with a clear error if it's ambiguous or matches no one.
Inputs: board (required), days, since, before, +3 more. Returns: events, memberId, truncated, matchedEvents, +2 more
get_overdue_cardsGet Overdue CardsA
Cards with a past-due date that aren't marked complete and aren't archived, based on the board's current card state (not action history). Sorted most-overdue first.
Inputs: board (required), listId, memberId. Returns: board, cards, evaluatedAt, totalOverdue
get_stale_cardsGet Stale CardsA
Returns open cards with no recognized activity (creation, list move, archive/unarchive) for at least staleDays (default 14). Stale does not imply blocked — Trello data alone can't say why a card hasn't moved. When the underlying action history couldn't be fully scanned, affected cards are still returned but marked historyComplete: false rather than silently assumed stale.
Inputs: board (required), listId, memberId, staleDays, +1 more. Returns: cards, truncated, totalStale, evaluatedAt, +2 more
get_top_card_moversGet Top Card MoversA
Ranks board members by list-to-list card movements in a date range (explicit since/before, or the convenience days — default last 7 days if neither is given). This is a Trello workflow-activity metric (cardsMoved), not employee productivity or performance.
Inputs: board (required), days, limit, since, +2 more. Returns: movers, truncated, actionsScanned, requestedRange, +1 more
get_upcoming_due_cardsGet Upcoming Due CardsA
Cards due within the next N days (default 7) that aren't marked complete and aren't archived, based on the board's current card state (not action history). Sorted soonest-due first.
Inputs: board (required), listId, memberId, withinDays. Returns: cards, withinDays, evaluatedAt, totalUpcoming
health_checkHealth CheckA
Checks that the trello-ops-mcp server is running and reachable. Requires no Trello credentials — useful for verifying the MCP connection itself before troubleshooting anything else.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target a distinct resource and concern (boards, lists, members, cards, actions). The main overlap is between get_board_actions, get_list_changes, get_card_movements, and get_member_activity, but the descriptions explicitly differentiate raw history from normalized/audit views and direct users to the intended tool.
All tools follow a consistent get_* pattern with descriptive noun phrases (e.g., get_board_lists, get_list_changes, get_top_card_movers). There is no mixing of styles or vague verbs, making the set predictable.
With 14 tools, the set is well-scoped for a Trello operations/monitoring server. Each tool addresses a specific query need without redundancy, and the count sits comfortably within the ideal range.
The server covers the core read/monitoring surface for Trello boards: lists, members, cards, activity, and action history. The only notable gap is a single-card detail endpoint, but get_board_cards already provides raw card data, so agents can work around this minor omission.
Maintenance
Related MCP Connectors
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
The fact infrastructure for agentic companies. Verified, versioned business facts over MCP.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that provides AI assistants with access to Trello's functionality. This server enables AI models to interact with Trello boards, lists, and cards programmatically.1MIT
- AlicenseBqualityDmaintenanceAn MCP server for the Trello REST API. Exposes ~36 curated tools for boards, lists, cards, checklists, labels, members, and search.368 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server that integrates Trello with AI agents, enabling natural language management of boards, lists, cards, checklists, attachments, and custom fields.2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that provides a real-time project management board with cards, sprints, comments, and docs, enabling coding agents to query and edit project state.2MIT