Fizzy-MCP

An MCP (Model Context Protocol) server for Fizzy, Basecamp's open-source Kanban tool.

What is MCP?

Model Context Protocol lets AI assistants (like Claude) use external tools. This server gives Claude the ability to manage your Fizzy boards and cards.

Quick Start

1. Install

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

2. Get a Fizzy API Token

1. Open your Fizzy instance (e.g., http://localhost:3000)
2. Click your avatar → My profile
3. Go to Access Tokens
4. Click Generate a new access token
5. Enter a description (e.g., "MCP Server")
6. Select Read + Write permission
7. Copy the token (you won't see it again!)

3. Configure Your Claude Client

Claude Code (macOS/Linux)

Edit ~/.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"
      }
    }
  }
}

Claude Desktop (macOS)

Edit ~/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"
      }
    }
  }
}

Then restart Claude.

4. Use It

Ask Claude things like:

• "List my Fizzy boards"
• "Create a card called 'Fix login bug' on the Ravenus board"
• "Move card 15 to Done"
• "Add a comment to card 12"

Environment Variables

Variable	Description	Default
FIZZY_URL	Your Fizzy instance URL	http://localhost:3000
FIZZY_TOKEN	API access token	(required)
FIZZY_ACCOUNT_ID	Account ID (from URL path)	1

Available Tools

Boards

Tool	Description
fizzy_list_boards	List all boards in the account
fizzy_get_board	Get details of a specific board
fizzy_create_board	Create a new board

Cards

Tool	Description
fizzy_list_cards	List all cards (optionally filter by board_id)
fizzy_get_card	Get card details
fizzy_create_card	Create a new card
fizzy_update_card	Update card title/description
fizzy_move_card	Move to column, "done", or "not_now"

Tags

Tool	Description
fizzy_add_tag	Add a tag to a card (creates tag if needed)
fizzy_remove_tag	Remove a tag from a card

Columns & Comments

Tool	Description
fizzy_list_columns	List columns on a board
fizzy_add_comment	Add a comment to a card
fizzy_list_comments	List comments on a card

Examples

Create a card with HTML description

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

The MCP server supports HTML in descriptions:

Fix the connection pooling issue.

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

Move cards through workflow

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

Tag cards

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

Tags are created automatically if they don't exist.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

Testing Manually

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

Troubleshooting

406 Not Acceptable

• Check that FIZZY_TOKEN is set and valid
• Verify the token has Read + Write permissions

Connection refused

• Ensure Fizzy is running at the configured URL
• Check the port matches your Fizzy setup

Card not found

• Card IDs are the card number (e.g., 11), not the CUID

License

MIT