使用说明

泡沫MCP

MCP（模型上下文协议）服务器嘶嘶冒泡的Basecamp的开源看板工具。

什么是MCP？

模型上下文协议让人工智能助手（如克劳德）使用外部工具。此服务器使Claude能够管理您的Fizzy板和卡。

快速开始

1.安装

git clone https://github.com/clawdcraft/fizzy-mcp.git
cd fizzy-mcp
npm install
npm run build

2.获取一个Fizzy API代币

打开你的Fizzy实例（例如。， http://localhost:3000)
点击您的头像→ 我的个人资料
首选 访问令牌
点击 生成新的访问令牌
输入描述（例如“MCP服务器”）
选择 读+写 许可
复制令牌（您将不会再看到它！）

3.配置您的Claude客户端

克劳德代码（macOS/Linux）

编辑 ~/.claude.json:

{
  "mcpServers": {
    "fizzy": {
      "command": "node",
      "args": ["/full/path/to/fizzy-mcp/dist/index.js"],
      "env": {
        "FIZZY_URL": "http://localhost:3000",
        "FIZZY_TOKEN": "your-api-token-here",
        "FIZZY_ACCOUNT_ID": "1"
      }
    }
  }
}

克劳德桌面（macOS）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fizzy": {
      "command": "node",
      "args": ["/full/path/to/fizzy-mcp/dist/index.js"],
      "env": {
        "FIZZY_URL": "http://localhost:3000",
        "FIZZY_TOKEN": "your-api-token-here",
        "FIZZY_ACCOUNT_ID": "1"
      }
    }
  }
}

然后重启克劳德。

4.使用它

问克劳德这样的问题：

“列出我的Fizzy板”
“在Ravenus板上创建一张名为“修复登录错误”的卡”
“将卡15移到完成”
“在卡片12上添加注释”

环境变量

变量	描述	默认值
`FIZZY_URL`	您的Fizzy实例URL	`http://localhost:3000`
`FIZZY_TOKEN`	API访问令牌	（必填）
`FIZZY_ACCOUNT_ID`	帐户ID（来自URL路径）	`1`

可用工具

板子

工具	说明
`fizzy_list_boards`	列出帐户中的所有板
`fizzy_get_board`	获取特定电路板的详细信息
`fizzy_create_board`	创建新板

卡片

工具	说明
`fizzy_list_cards`	列出所有卡（可选按board_id筛选）
`fizzy_get_card`	获取卡详细信息
`fizzy_create_card`	创建新卡
`fizzy_update_card`	更新卡片标题/描述
`fizzy_move_card`	移动到列、“完成”或“未完成”

专栏和评论

工具	说明
`fizzy_list_columns`	在板上列出列
`fizzy_add_comment`	在卡片上添加评论
`fizzy_list_comments`	在卡片上列出评论

例子

创建带有HTML描述的卡片

Create a card on board "03fjavj4afm5qrvuvluoi0po9" with:
- Title: "🔧 Fix database connection"
- Description with a link to the GitHub issue

MCP服务器在描述中支持HTML：

Fix the connection pooling issue.

📄 <a href="https://github.com/example/repo/issues/42">Issue #42</a>

在工作流程中移动卡片

Move card 15 to "done"
Move card 12 to "not_now"

标签卡

Add tag "bug" to card 15
Remove tag "feature" from card 12

如果标签不存在，则会自动创建标签。

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

手动测试

export FIZZY_URL="http://localhost:3000"
export FIZZY_TOKEN="your-token"
export FIZZY_ACCOUNT_ID="1"

# List tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fizzy_list_boards","arguments":{}}}' | node dist/index.js

故障排除

406不可接受

检查一下 FIZZY_TOKEN 已设置且有效
验证令牌是否具有读写权限

连接被拒绝

确保Fizzy正在配置的URL上运行
检查端口是否与Fizzy设置匹配

找不到卡

卡ID就是卡数字（例如。， 11)，而不是CUID

许可证

麻省理工学院

工具	说明
`fizzy_add_tag`	在卡片上添加标签（必要时创建标签）
`fizzy_remove_tag`	从卡片上删除标签