fizzy-mcp

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: ```html 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