# 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
<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`
```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:
```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."
</details>
<details>
<summary><b>Cursor</b></summary>
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).
</details>
<details>
<summary><b>VS Code</b></summary>
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".
</details>
<details>
<summary><b>Windsurf</b></summary>
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.
</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`
```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`:
```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](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.
</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:
```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
