shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

fizzy-mcp

Fizzy任务管理的MCP服务器，提供看板、卡片、评论和清单的管理工具

article

README

🚀 fizzy-mcp

fizzy-mcp 是一个用于 Fizzy 任务管理的 MCP 服务器，它提供了 7 种工具，可用于管理看板、卡片、评论和清单。

🚀 快速开始

在使用 fizzy-mcp 之前，你需要获取 Fizzy 的访问令牌：

  1. 登录 Fizzy。
  2. 进入设置 > API 访问。
  3. 生成一个新的令牌。

📦 安装指南

Claude Desktop

将以下配置添加到你的配置文件中：

  • 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： 在 env 块中添加 "APPDATA": "C:\\Users\\YourUsername\\AppData\\Roaming"。

完全重启 Claude Desktop，然后验证："List my Fizzy boards."

Claude Code

使用 CLI 命令：

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

或者将以下配置添加到 ~/.claude.json：

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

重启 Claude Code，然后验证："List my Fizzy boards."

Cursor

将以下配置添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

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

完全重启 Cursor，然后在代理模式（Ctrl+I）下验证。

VS Code

将以下配置添加到工作区的 .vscode/mcp.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}"
      }
    }
  }
}

或者通过命令面板 → "MCP: Open User Configuration" 使用用户设置。

Windsurf

将以下配置添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "Fizzy": {
      "command": "npx",
      "args": ["-y", "@silky/fizzy-mcp"],
      "env": {
        "FIZZY_TOKEN": "${env:FIZZY_TOKEN}"
      }
    }
  }
}

在你的 shell 环境中设置 FIZZY_TOKEN，或者硬编码该值。重启 Windsurf。

Cline

将以下配置添加到 Cline MCP 设置文件：

  • 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": []
    }
  }
}

Continue

将以下配置添加到 .continue/config.yaml：

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

从源代码安装

需要 pnpm。

git clone https://github.com/davegomez/fizzy-mcp.git
cd fizzy-mcp
pnpm install
pnpm build

在上述任何配置中，将 npx -y @silky/fizzy-mcp 替换为 node /absolute/path/to/fizzy-mcp/dist/index.js。

📚 详细文档

配置参考

| 变量 | 是否必需 | 默认值 | 描述 | | ---------------- | -------- | ---------------------- | ------------------------------------ | | FIZZY_TOKEN | 是 | — | 从 Fizzy 设置中获取的 API 令牌 | | FIZZY_ACCOUNT | 否 | — | 默认账户 slug（例如，897362094） | | FIZZY_BASE_URL | 否 | https://app.fizzy.do | API 基础 URL |

账户解析

工具按以下顺序解析 account_slug：

  1. 工具调用时显式指定的 account_slug 参数。
  2. 会话默认值（通过 fizzy_account 工具设置，action: "set"）。
  3. FIZZY_ACCOUNT 环境变量。
  4. 自动检测（如果用户只有一个账户）。

工具参考

fizzy_account

获取、设置或列出后续工具调用的账户。 | 参数 | 类型 | 是否必需 | 描述 | | -------------- | ------------------------------ | -------- | ---------------------------- | | action | "get" | "set" | "list" | 是 | 要执行的操作 | | account_slug | string | 仅 set | 从 Fizzy URL 中获取的账户 slug |

返回值：

  • get: { "action": "get", "account_slug": "897362094" | null }
  • set: { "action": "set", "account_slug": "897362094" }
  • list: { "action": "list", "accounts": [{ "slug": "...", "name": "...", "id": "..." }] }

fizzy_boards

列出账户中的看板，并提供列摘要。 | 参数 | 类型 | 是否必需 | 默认值 | 描述 | | -------------- | ------ | -------- | --------------- | -------------- | | account_slug | string | 否 | 会话默认值 | 账户 slug | | limit | number | 否 | 25 | 每页项目数 (1 - 100) | | cursor | string | 否 | — | 分页游标 |

返回值： { "items": Board[], "pagination": { "returned": number, "has_more": boolean, "next_cursor"?: string } }

fizzy_search

使用过滤器搜索卡片。 | 参数 | 类型 | 是否必需 | 描述 | | ----------------- | ---------------------------------------------------------------------------------------- | -------- | ---------------------------- | | account_slug | string | 否 | 账户 slug | | board_id | string | 否 | 按看板过滤 | | tag_ids | string[] | 否 | 按所有标签过滤 | | assignee_ids | string[] | 否 | 按任何分配人过滤 | | creator_ids | string[] | 否 | 按卡片创建者过滤 | | closer_ids | string[] | 否 | 按关闭者过滤 | | card_ids | string[] | 否 | 过滤到特定卡片 ID | | indexed_by | "closed" | "not_now" | "all" | "stalled" | "postponing_soon" | "golden" | 否 | 按索引过滤 | | assignment_status | "unassigned" | 否 | 按分配状态过滤 | | sorted_by | "newest" | "oldest" | "recently_active" | 否 | 排序顺序 | | terms | string[] | 否 | 自由文本搜索词 | | creation | 日期范围* | 否 | 按创建日期过滤 | | closure | 日期范围* | 否 | 按关闭日期过滤 | | limit | number | 否 | 每页项目数 (1 - 100, 默认 25) | | cursor | string | 否 | 分页游标 |

*日期范围值：today, yesterday, thisweek, thismonth, last7, last14, last30。

返回值： { "items": Card[], "pagination": {...} }

fizzy_get_card

通过编号或 ID 获取卡片的完整详细信息。 | 参数 | 类型 | 是否必需 | 描述 | | -------------- | ------ | -------- | ------------------------------------ | | account_slug | string | 否 | 账户 slug | | card_number | number | 否* | 从 URL 中获取的卡片编号（例如，#42 中的 42） | | card_id | string | 否* | 从 API 响应中获取的卡片 UUID |

*提供 card_number 或 card_id。当你有 UI 中可读的 # 时，优先使用 card_number。

返回值： 包含 id, number, title, description（markdown 格式）, status, board_id, column_id, tags, assignees, steps_count, completed_steps_count, comments_count, url, 时间戳的卡片对象。

fizzy_task

创建或更新卡片。 模式： 省略 card_number 以创建；包含它以更新。 | 参数 | 类型 | 是否必需 | 描述 | | -------------- | ------------------------------------- | ----------- | ------------------------------------ | | account_slug | string | 否 | 账户 slug | | card_number | number | 否 | 要更新的卡片（省略以创建） | | board_id | string | 创建模式 | 新卡片所在的看板 | | title | string | 创建模式 | 卡片标题 | | description | string | 否 | Markdown 内容 | | status | "open" | "closed" | "not_now" | 否 | 更改卡片状态 | | column_id | string | 否 | 分类到列 | | position | "top" | "bottom" | 否 | 列中的位置（默认："bottom"） | | add_tags | string[] | 否 | 要添加的标签标题 | | remove_tags | string[] | 否 | 要移除的标签标题 | | steps | string[] | 否 | 清单项目（仅创建模式） |

返回值： { "mode": "create" | "update", "card": {...}, "operations": {...}, "failures": [...] }

fizzy_comment

在卡片上创建、列出、更新或删除评论。 | 参数 | 类型 | 是否必需 | 描述 | | -------------- | ------ | -------- | ------------------------------------------------------------- | | action | string | 否 | "create"（默认）, "list", "update", "delete" | | account_slug | string | 否 | 账户 slug | | card_number | number | 是 | 卡片编号 | | comment_id | string | 否 | 评论 ID。更新/删除时必需 | | body | string | 否 | Markdown 格式的评论（1 - 10000 个字符）。创建/更新时必需 |

返回值： 包含 id, body（markdown 格式）, creator, 时间戳, url 的评论对象。列表返回 { comments, pagination }。删除返回 { comment_id, deleted }。

fizzy_step

在卡片上创建、完成、更新、取消完成或删除步骤。 | 参数 | 类型 | 是否必需 | 描述 | | -------------- | ---------------- | -------- | ------------------------------------------------ | | account_slug | string | 否 | 账户 slug | | card_number | number | 是 | 包含步骤的卡片 | | step | string | number | 否 | 内容子字符串或基于 1 的索引。省略以创建。 | | content | string | 否 | 创建或更新步骤的文本 | | completed | boolean | 否 | 设置完成状态 | | delete | boolean | 否 | 删除步骤 |

模式检测：

  • step 缺失 → 创建（需要 content）
  • step 存在，无其他参数 → 完成
  • step + content → 更新
  • step + completed: false → 取消完成
  • step + delete: true → 删除

返回值： { "id": "...", "content": "...", "completed": true }

分页参考

列表操作返回：

{
  "items": [...],
  "pagination": {
    "returned": 25,
    "has_more": true,
    "next_cursor": "opaque-cursor-string"
  }
}

| 字段 | 类型 | 描述 | | ------------- | ------- | ---------------------------- | | returned | number | 此响应中的项目数 | | has_more | boolean | 是否有更多项目 | | next_cursor | string | 作为 cursor 传递以获取下一页 |

错误参考

| 错误 | 原因 | | ------------------------------------------------------------------------------------------------ | ------------------------------------------ | | "No account specified. Set FIZZY_ACCOUNT env var, use fizzy_account tool, or pass account_slug." | 无法通过任何方法解析账户 | | "Account "..." not found" | 传递给 fizzy_account set 的 slug 无效 | | "Card #N not found" | 卡片编号不存在 | | "Board not found" | board_id 无效 |

📄 许可证

本项目采用 AGPL-3.0-or-later 许可证。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client