# davegomez/fizzy-mcp [Health: Active] **Category:** 🏢 Workplace & Productivity **Repository:** https://github.com/davegomez/fizzy-mcp **GitHub Stars:** 3 **npm Downloads (last month):** 194 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/davegomez-fizzy-mcp ## Description MCP server for Fizzy kanban task management with tools for boards, cards, comments, and checklists. ## Tools Capabilities this server exposes over MCP: - **fizzy_account** — 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. - **fizzy_boards** — 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. ```json {"items": [{"id": "board_1", "name": "Project", "columns": [{"id": "col_1", "name": "Backlog"}]}], "pagination": {...}} ``` **Related:** Use board ID with `fizzy_task` to create cards. Use column IDs for triage. - **fizzy_search** — 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. ```json {"items": [{"number": 42, "title": "...", ...}], "pagination": {"returned": 25, "has_more": true, "next_cursor": "..."}} ``` **Related:** Use card number with `fizzy_get_card` for full details. - **fizzy_get_card** — 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. - **fizzy_task** — 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"]}` - **fizzy_comment** — 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. - **fizzy_step** — 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}` ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "fizzy-mcp": { "command": "npx", "args": ["-y","@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "", "FIZZY_ACCOUNT": "", "FIZZY_BASE_URL": "" } } } ``` **Requires environment variables:** `FIZZY_TOKEN`, `FIZZY_ACCOUNT`, `FIZZY_BASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README # fizzy-mcp MCP server for [Fizzy](https://fizzy.do) task management. Exposes 7 tools for managing boards, cards, comments, and checklists. ## Prerequisites Get your Fizzy access token: 1. Log in to [Fizzy](https://app.fizzy.do) 2. Go to Settings > API Access 3. Generate a new token ## How to Install
Claude Desktop Add to your config file: - **macOS:** `~/Library/Application\ Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **Linux:** `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "your-token-here" } } } } ``` **Windows only:** Add `"APPDATA": "C:\\Users\\YourUsername\\AppData\\Roaming"` to the `env` block. Restart Claude Desktop completely, then verify: "List my Fizzy boards."
Claude Code Use the CLI: ```bash claude mcp add --transport stdio Fizzy --env FIZZY_TOKEN=your-token-here -- npx -y @silky/fizzy-mcp ``` Or add to `~/.claude.json`: ```json { "mcpServers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "your-token-here" } } } } ``` Restart Claude Code, then verify: "List my Fizzy boards."
Cursor Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "your-token-here" } } } } ``` Restart Cursor completely, then verify in Agent mode (Ctrl+I).
VS Code Add to `.vscode/mcp.json` in your workspace: ```json { "inputs": [ { "type": "promptString", "id": "fizzy-token", "description": "Fizzy API Token", "password": true } ], "servers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "${input:fizzy-token}" } } } } ``` Or use user settings via Command Palette → "MCP: Open User Configuration".
Windsurf Add to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "${env:FIZZY_TOKEN}" } } } } ``` Set `FIZZY_TOKEN` in your shell environment, or hardcode the value. Restart Windsurf.
Cline Add to the Cline MCP settings file: - **macOS:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - **Windows:** `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - **Linux:** `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ```json { "mcpServers": { "Fizzy": { "command": "npx", "args": ["-y", "@silky/fizzy-mcp"], "env": { "FIZZY_TOKEN": "your-token-here" }, "disabled": false, "alwaysAllow": [] } } } ```
Continue Add to `.continue/config.yaml`: ```yaml mcpServers: - name: Fizzy command: npx args: - "-y" - "@silky/fizzy-mcp" env: FIZZY_TOKEN: ${{ secrets.FIZZY_TOKEN }} ```
From Source **Requires [pnpm](https://pnpm.io/).** ```bash git clone https://github.com/davegomez/fizzy-mcp.git cd fizzy-mcp pnpm install pnpm build ``` Replace `npx -y @silky/fizzy-mcp` with `node /absolute/path/to/fizzy-mcp/dist/index.js` in any config above.
--- ## Configuration Reference | Variable | Required | Default | Description | | ---------------- | -------- | ---------------------- | ---------------------------------------- | | `FIZZY_TOKEN` | Yes | — | API token from Fizzy settings | | `FIZZY_ACCOUNT` | No | — | Default account slug (e.g., `897362094`) | | `FIZZY_BASE_URL` | No | `https://app.fizzy.do` | API base URL | ### Account Resolution Tools resolve `account_slug` in this order: 1. Explicit `account_slug` parameter on the tool call 2. Session default (set via `fizzy_account` tool with `action: "set"`) 3. `FIZZY_ACCOUNT` environment variable 4. Auto-detect (if user has exactly one account) --- ## Tools Reference ### fizzy_account Gets, sets, or lists accounts for subsequent tool calls. | Parameter | Type | Required | Description | | -------------- | ------------------------------ | --------- | --------------------------- | | `action` | `"get"` \| `"set"` \| `"list"` | Yes | Action to perform | | `account_slug` | string | For `set` | Account slug from Fizzy URL | **Returns:** - `get`: `{ "action": "get", "account_slug": "897362094" | null }` - `set`: `{ "action": "set", "account_slug": "897362094" }` - `list`: `{ "action": "list", "accounts": [{ "slug": "...", "name": "...", "id": "..." }] }` --- ### fizzy_boards Lists boards in the account with column summaries. | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | --------------- | ---------------------- | | `account_slug` | string | No | Session default | Account slug | | `limit` | number | No | 25 | Items per page (1-100) | | `cursor` | string | No | — | Pagination cursor | **Returns:** `{ "items": Board[], "pagination": { "returned": number, "has_more": boolean, "next_cursor"?: string } }` --- ### fizzy_search Searches for cards with filters. | Parameter | Type | Required | Description | | ------------------- | ---------------------------------------------------------------------------------------- | -------- | ---------------------------------- | | `account_slug` | string | No | Account slug | | `board_id` | string | No | Filter by board | | `tag_ids` | string[] | No | Filter by ALL tags | | `assignee_ids` | string[] | No | Filter by ANY assignees | | `creator_ids` | string[] | No | Filter by card creator | | `closer_ids` | string[] | No | Filter by who closed | | `card_ids` | string[] | No | Filter to specific card IDs | | `indexed_by` | `"closed"` \| `"not_now"` \| `"all"` \| `"stalled"` \| `"postponing_soon"` \| `"golden"` | No | Filter by index | | `assignment_status` | `"unassigned"` | No | Filter by assignment status | | `sorted_by` | `"newest"` \| `"oldest"` \| `"recently_active"` | No | Sort order | | `terms` | string[] | No | Free-text search terms | | `creation` | date range\* | No | Filter by creation date | | `closure` | date range\* | No | Filter by closure date | | `limit` | number | No | Items per page (1-100, default 25) | | `cursor` | string | No | Pagination cursor | \*Date range values: `today`, `yesterday`, `thisweek`, `thismonth`, `last7`, `last14`, `last30`. **Returns:** `{ "items": Card[], "pagination": {...} }` --- ### fizzy_get_card Gets full details of a card by number or ID. | Parameter | Type | Required | Description | | -------------- | ------ | -------- | -------------------------------------------- | | `account_slug` | string | No | Account slug | | `card_number` | number | No\* | Card number from URL (e.g., `42` from `#42`) | | `card_id` | string | No\* | Card UUID from API responses | \*Provide `card_number` OR `card_id`. Prefer `card_number` when you have the human-readable `#` from the UI. **Returns:** Card object with `id`, `number`, `title`, `description` (markdown), `status`, `board_id`, `column_id`, `tags`, `assignees`, `steps_count`, `completed_steps_count`, `comments_count`, `url`, timestamps. --- ### fizzy_task Creates or updates a card. **Mode:** Omit `card_number` to create; include it to update. | Parameter | Type | Required | Description | | -------------- | ------------------------------------- | ----------- | ---------------------------------------- | | `account_slug` | string | No | Account slug | | `card_number` | number | No | Card to update (omit to create) | | `board_id` | string | Create mode | Board for new card | | `title` | string | Create mode | Card title | | `description` | string | No | Markdown content | | `status` | `"open"` \| `"closed"` \| `"not_now"` | No | Change card status | | `column_id` | string | No | Triage to column | | `position` | `"top"` \| `"bottom"` | No | Position in column (default: `"bottom"`) | | `add_tags` | string[] | No | Tag titles to add | | `remove_tags` | string[] | No | Tag titles to remove | | `steps` | string[] | No | Checklist items (create mode only) | **Returns:** `{ "mode": "create" | "update", "card": {...}, "operations": {...}, "failures": [...] }` --- ### fizzy_comment Create, list, update, or delete a comment on a card. | Parameter | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------------------- | | `action` | string | No | `"create"` (default), `"list"`, `"update"`, `"delete"` | | `account_slug` | string | No | Account slug | | `card_number` | number | Yes | Card number | | `comment_id` | string | No | Comment ID. Required for update/delete | | `body` | string | No | Comment in markdown (1-10000 chars). Required for create/update | **Returns:** Comment object with `id`, `body` (markdown), `creator`, timestamps, `url`. List returns `{ comments, pagination }`. Delete returns `{ comment_id, deleted }`. --- ### fizzy_step Create, complete, update, uncomplete, or delete a step on a card. | Parameter | Type | Required | Description | | -------------- | ---------------- | -------- | --------------------------------------------------- | | `account_slug` | string | No | Account slug | | `card_number` | number | Yes | Card containing the step | | `step` | string \| number | No | Content substring OR 1-based index. Omit to create. | | `content` | string | No | Step text for create or update | | `completed` | boolean | No | Set completion state | | `delete` | boolean | No | Delete the step | **Mode detection:** - `step` absent → CREATE (requires `content`) - `step` present, no other params → COMPLETE - `step` + `content` → UPDATE - `step` + `completed: false` → UNCOMPLETE - `step` + `delete: true` → DELETE **Returns:** `{ "id": "...", "content": "...", "completed": true }` --- ## Pagination Reference List operations return: ```json { "items": [...], "pagination": { "returned": 25, "has_more": true, "next_cursor": "opaque-cursor-string" } } ``` | Field | Type | Description | | ------------- | ------- | ------------------------------ | | `returned` | number | Items in this response | | `has_more` | boolean | More items available | | `next_cursor` | string | Pass as `cursor` for next page | --- ## Error Reference | Error | Cause | | ------------------------------------------------------------------------------------------------ | ------------------------------------------ | | "No account specified. Set FIZZY_ACCOUNT env var, use fizzy_account tool, or pass account_slug." | No account resolvable via any method | | "Account \"...\" not found" | Invalid slug passed to `fizzy_account` set | | "Card #N not found" | Card number does not exist | | "Board not found" | Invalid `board_id` | --- ## License AGPL-3.0-or-later