teamboard-mcp

MCP server for TeamBoard. Lets any MCP-aware client (Claude Code, etc.) read and write TeamBoard tasks over the HTTP API.

You never pass an ObjectId. Tasks are referenced by TASK-42 (any casing or zero-padding) or by title; people by name, email or username; projects by code or name. When a reference is ambiguous the tool returns the candidate list instead of guessing — so an edit never lands on the wrong task or the wrong assignee.

Usage (no install)

Add this to your Claude Code MCP config (~/.claude.json, or .mcp.json in any project):

{
  "mcpServers": {
    "teamboard": {
      "command": "npx",
      "args": ["-y", "github:uplsuman/teamboard-mcp"],
      "env": {
        "TEAMBOARD_BASE_URL": "https://teamboard.utplco.com",
        "TEAMBOARD_TOKEN": "tbp_..."
      }
    }
  }
}

Generate the token in TeamBoard → Settings → API Tokens. Grant the scopes for what you want it to do:

MCP servers only pick up env changes on restart — run /mcp to reconnect after changing the token.

Working rules

The server sends these to every client as its instructions, so an agent follows them without being told each time. The text lives in INSTRUCTIONS in index.js; change both together.

Writing tickets and comments

• Write for a person, not a codebase: what the user sees, what was wrong, what happens

now, how to check it. Function names and file paths belong in the PR.

• Keep comments short: a fix comment is two or three sentences (what was wrong, what

happens now) plus the screenshot, not a report with headings and lists.

• description and comment are literal HTML (<h3>, <p>, <ul>/<li>, <strong>,

<code>). Send the tags raw. <p> is stored as-is and shows up as text.

• A task's endDate is labelled Due Date.
• No AI or tool attribution ("Generated with…", "Co-Authored-By") in ticket text.
• Mention with `@[Name]` or `@[email]`. In any description or comment, the server

turns it into a real mention chip, so the person is notified and added as a watcher. The name is resolved like an assignee, so an ambiguous one fails with the candidates instead of tagging the wrong person. A plain @Name stays plain text.

Screenshots

• Creating a ticket: attach a screenshot of the problem (add_teamboard_attachment

right after create_teamboard_task) and mention it in the description.

• After a fix: comment with a screenshot of the fixed behaviour

(comment_teamboard_task { files }). The same screenshot goes in the PR description.

Creating

• Search first (search_teamboard_tasks) to catch duplicates.
• Follow-up work related to an open ticket goes on that ticket as a comment or edit,

not a new ticket.

• Type defaults to Task and priority to Low. Don't ask for them.

Working a ticket

• Before writing code: move the ticket to an in-progress status with

trackerDecision: "foreground", which starts its timer. No ticket for the work? Ask, or create one.

• If a foreground timer is already running (it may belong to another session), use

"background". Never pause or stop the other timer. log_teamboard_time is for time that was genuinely missed, not the normal way to record work.

• Moving into in-progress needs a due date. Changing an active task's due date needs a

clarification (10+ characters, 2+ words).

• Entering a testing or done status needs a resolution.
• PR raised: move the ticket to PR In Review and stop its timer with

stop_teamboard_timer. The status change alone may not stop it.

Tools

Notes that bite:

• Rich text is HTML. description and comment take literal

<h3>/<ul>/<li>/<strong>/<code> markup, not plain text with newlines.

• Mentions are `@[Name]` (see Working rules); the brackets are what make it a mention.
• An assignee must be a member of the task's project. list_teamboard_users

with project shows who is eligible; the assignee lookup is scoped to that roster, so a non-member name fails with the roster rather than picking someone.

• `tags` replaces the whole list — pass every tag you want to keep.
• `"none"` clears assignee, project, parent or type.
• **Statuses, priorities, task types and resolutions are read from the workspace at

startup**, so the tool descriptions list your real values and a typo is rejected locally. Resolutions are the one exception to local rejection: a project may override the workspace list, so the value is sent as given and the server judges it.

• Moving a task to another project changes its task id; the tool reports the new one.
• Two arguments are mandatory for the moves that need them, not optional extras:
• resolution — moving a task into a testing or done status (In Testing,

Completed, Cancelled, Closed…). A status says where a task is; the resolution says how it ended, and the move is refused without one. Testing → done carries the resolution already given, so it isn't asked twice.

• trackerDecision — moving a task into an in-progress status, which would start

the assignee's timer. Pass skip to change the status without starting a timer, or foreground to start it. The other values resolve a clash when that person is already tracking something.

• Other server rules surface as tool errors and need a follow-up argument:

clarification (10+ chars, 2+ words) when an active task's due date changes, and a due date before a task can move into in-progress ("Please add the end date first").

Development

pnpm install
node test.mjs            # resolution tests, no network (fetch is stubbed)

TEAMBOARD_BASE_URL=http://localhost:3000 TEAMBOARD_TOKEN=tbp_xxx node index.js

resolve.js holds the API client and the reference resolvers; index.js is only tool definitions and formatting.

Performance notes

• Sections load in parallel. get_teamboard_task with a full include issues its

five sub-requests together rather than one after another.

• Resolutions are cached for 60s. The same project code or person's name costs one

round trip per minute, not one per tool call. The TTL is deliberately short: a stale hit here would address the wrong row. invalidateCache() clears it.

• Every request has a 30s timeout, and an unreachable server fails with the base

URL in the message instead of hanging the tool call.

• Long lists are capped (25 rows per section, 4 children per digest notification)

with an "…and N more" line, so one busy task cannot bury the rest of a reply.

• Tool schemas cost ~5.4k tokens for 28 tools. The workspace vocabulary is listed

once per tool, on the field that needs it, not repeated in the description.

Attachments are addressed by name, never by their storage URL, and an ambiguous name lists the candidates rather than picking one — deleting the wrong file is not recoverable.

Requires

TeamBoard with personal-access-token support on /api/tasks, /api/tasks/meta, /api/tasks/statuses, /api/tasks/:id/{subtasks,links,activities,github}, /api/projects, /api/projects/:id/members, /api/users, /api/users/me, /api/comments, /api/comments/:id and /api/uploads/* (TB dev after Sep 2026).