fizzy-mcp

fizzy-mcp

MCP server for Fizzy task management. Exposes 7 tools for managing boards, cards, comments, and checklists.

Prerequisites

Get your Fizzy access token:

1. Log in to Fizzy
2. Go to Settings > API Access
3. Generate a new token

How to Install

<details> <summary><b>Claude Desktop</b></summary>

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

{
  "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."

</details>

<details> <summary><b>Claude Code</b></summary>

Use the CLI:

claude mcp add --transport stdio Fizzy --env FIZZY_TOKEN=your-token-here -- npx -y @silky/fizzy-mcp

Or add to ~/.claude.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."

</details>

<details> <summary><b>Cursor</b></summary>

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "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).

</details>

<details> <summary><b>VS Code</b></summary>

Add to .vscode/mcp.json in your workspace:

{
  "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".

</details>

<details> <summary><b>Windsurf</b></summary>

Add to ~/.codeium/windsurf/mcp_config.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.

</details>

<details> <summary><b>Cline</b></summary>

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

{
  "mcpServers": {
    "Fizzy": {
      "command": "npx",
      "args": ["-y", "@silky/fizzy-mcp"],
      "env": {
        "FIZZY_TOKEN": "your-token-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

</details>

<details> <summary><b>Continue</b></summary>

Add to .continue/config.yaml:

mcpServers:
  - name: Fizzy
    command: npx
    args:
      - "-y"
      - "@silky/fizzy-mcp"
    env:
      FIZZY_TOKEN: ${{ secrets.FIZZY_TOKEN }}

</details>

<details> <summary><b>From Source</b></summary>

Requires pnpm.

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.

</details>

---

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:

{
  "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