fizzy-mcp

Get, set, or list accounts for API calls.

Manages the session default so you don't need to pass account_slug on every tool call.

When to use:

• List available accounts to see what you have access to

• Set working account after discovering accounts

• Check current default before operations

Don't use when: Operating across multiple accounts simultaneously — pass account_slug explicitly instead.

Arguments:

• action (required): "get" to check current default, "set" to change it, "list" to see available accounts

• account_slug (required for set): Account slug (e.g., "897362094")

Returns:

• get: { "action": "get", "account_slug": "897362094" } or null if not set

• set: { "action": "set", "account_slug": "897362094" }

• list: { "action": "list", "accounts": [{ "slug": "...", "name": "...", "id": "..." }] }

Related: Most tools auto-resolve account via FIZZY_ACCOUNT env var or single-account auto-detection.

List boards in the account with column summaries.

Get an overview of boards and their column structure including card counts.

When to use:

• Discover board IDs and column IDs for subsequent operations

• See card counts per column across all boards

• Find the right board/column to create cards or triage

Fizzy column conventions: Every board has three implicit columns not returned in the columns array:

• Maybe? (inbox): Untriaged cards. Cards here have no column_id. New cards start here.

• Not Now: Deferred cards. Move here via status: "not_now" in fizzy_task.

• Done: Closed cards. Move here via status: "closed" in fizzy_task.

The columns array only contains custom workflow columns (e.g., "In Progress", "Backlog"). To move a card from a column back to Maybe?, use fizzy_task with column_id omitted and no status change.

Arguments:

• account_slug (optional): Uses session default if omitted

• limit (optional): Max items to return, 1-100 (default: 25)

• cursor (optional): Continuation cursor from previous response

Returns: JSON with items and pagination metadata.

Related: Use board ID with fizzy_task to create cards. Use column IDs for triage.

Search for cards with filters. Find cards matching criteria or review board contents.

When to use:

• Find cards by tag, assignee, or board

• Filter by index category (closed, stalled, golden, etc.)

Don't use when: You already know the card number — use fizzy_get_card instead.

Arguments:

• account_slug (optional): Uses session default if omitted

• board_id (optional): Filter to cards on this board

• indexed_by (optional): Filter by index category: closed | not_now | all | stalled | postponing_soon | golden

• tag_ids (optional): Filter to cards with ALL these tag IDs

• assignee_ids (optional): Filter to cards assigned to ANY of these user IDs

• sorted_by (optional): Sort order: newest | oldest | recently_active

• terms (optional): Search terms to filter cards by text content

• limit (optional): Max items, 1-100 (default: 25)

• cursor (optional): Continuation cursor from previous response

Returns: JSON with items and pagination metadata.

Related: Use card number with fizzy_get_card for full details.

Get full details of a card by its number or ID. Retrieve complete card data including description, steps count, and metadata.

When to use:

• Need full description or metadata for a specific card

• Check step completion status or see all tags/assignees

Don't use when: Scanning multiple cards - use fizzy_search first.

Arguments:

• account_slug (optional): Uses session default if omitted

• card_number (recommended): The human-readable # number from URLs/lists (e.g., 42)

• card_id (alternative): The UUID from API responses. Use card_number when possible.

IMPORTANT: Provide card_number (integer) OR card_id (string UUID), not both. The card_number is the # visible in the UI (e.g., #42). The card_id is the internal UUID.

Returns: JSON with id, number, title, description (markdown), status, board_id, column_id, tags array, assignees array, steps_count, completed_steps_count, comments_count, url, created_at, updated_at, closed_at (null if open). Example: {"id": "card_abc", "number": 42, "title": "Fix bug", "status": "open", "steps_count": 3, ...}

Related: Use fizzy_comment or fizzy_step for deeper interaction.

Create or update a card with full control over status, tags, steps, and column placement.

Mode detection:

• card_number absent → CREATE mode (requires board_id + title)

• card_number present → UPDATE mode

Create mode: Creates card, then best-effort: adds steps, toggles tags, triages to column.

Update mode: Updates title/description if provided. Changes status (open/closed/not_now). Manages tags with add/remove. Moves card to column (from inbox or another column). Same-column moves are skipped.

Fizzy column conventions:

• Maybe? (inbox): Cards with no column_id. This is where new cards start.

• Not Now: Set status: "not_now" to move here (defers the card).

• Done: Set status: "closed" to move here (completes the card).

• Custom columns: Use column_id from fizzy_boards to triage to workflow columns.

Arguments:

• account_slug (optional): Uses session default if omitted

• card_number (optional): Card to update. Omit to create new card.

• board_id (optional): Board ID. Required for create mode.

• title (optional): Card title. Required for create mode.

• description (optional): Card body in markdown

• status (optional): open | closed | not_now — changes card lifecycle state

• column_id (optional): Move card to this column (works from inbox or other columns; skipped if already there)

• position (optional): top | bottom (default: bottom) — position in column

• add_tags (optional): Tag titles to add

• remove_tags (optional): Tag titles to remove

• steps (optional): Checklist items to create (create mode only)

Returns: JSON with mode, card (id, number, title, url, status), operations summary, failures array.

Examples: Create: {board_id: "...", title: "New task", steps: ["Step 1", "Step 2"]} Update: {card_number: 42, status: "closed", add_tags: ["done"]}

Manage comments on a card: create, list, update, or delete.

Actions:

• create (default): Post a new comment

• list: Get all comments on a card

• update: Edit an existing comment (requires comment_id + body)

• delete: Remove a comment (requires comment_id)

Arguments:

• action (optional): "create" | "list" | "update" | "delete" (default: "create")

• account_slug (optional): Uses session default if omitted

• card_number (required): Card number

• comment_id (optional): Required for update/delete

• body (optional): Comment body in markdown. Required for create/update

Returns: JSON with comment details, list of comments, or deletion confirmation.

Create, complete, update, uncomplete, or delete a step on a card.

Mode detection:

• step absent → CREATE (requires content)

• step present, no other params → COMPLETE (default action)

• step + content → UPDATE content

• step + completed: false → UNCOMPLETE

• step + delete: true → DELETE

Arguments:

• account_slug (optional): Uses session default if omitted

• card_number (required): Card number containing the step

• step (optional): Content substring to match OR 1-based index to identify existing step

• content (optional): Step text for create or update

• completed (optional): Set completion state (true or false)

• delete (optional): Delete the step

Returns: JSON with step id, content, completed status.

Examples:

• Create: {card_number: 42, content: "Write tests"}

• Complete: {card_number: 42, step: "Write tests"}

• Uncomplete: {card_number: 42, step: 1, completed: false}

• Update: {card_number: 42, step: 1, content: "Write unit tests"}

• Delete: {card_number: 42, step: "Write tests", delete: true}