fizzy

The Fizzy MCP server exposes a bridge to Fizzy, Basecamp's project management tool, enabling AI assistants and IDEs to interact with Fizzy boards, cards, and projects through the MCP interface. It supports multiple transports (stdio for local, HTTP streamable for multi-user deployments, and SSE for legacy compatibility) and provides tools to fetch, create, update, and organize Fizzy data via natural language prompts. Typical usage involves running the MCP server locally with your Fizzy access token and configuring your IDE (Cursor, VS Code, Claude Desktop, or other MCP-compatible tools) to connect to the running server, then issuing prompts that leverage Fizzy APIs for boards, cards, actions, comments, and more.

By default, the recommended setup uses the npx-based stdio transport for single-user development. For production or multi-user deployments, you would switch to the HTTP (Streamable) transport to enable token-based authentication per user and scalable usage across sessions. The server exposes 44 Fizzy API tools, covering entities such as Boards, Cards, Card Actions, Comments, Reactions, Steps, Columns, Tags, Users, and Notifications, and includes robust error handling, automatic retries, and ETag-based caching to improve performance.

Prerequisites:

• Node.js 18 or higher
• Internet access to install npm packages

Option A: Install globally from npm (recommended)

npm install -g fizzy-mcp

This makes the fizzy-mcp command available globally. You can then run the server using the stdio transport (single-user) by providing your Fizzy access token:

FIZZY_ACCESS_TOKEN="your-token-here" fizzy-mcp

Option B: Use with npx (no installation required)

npx fizzy-mcp

Option C: Build from source (advanced)

# Clone the repository
git clone https://github.com/Fabric-Pro/fizzy-mcp.git
cd fizzy-mcp

# Install dependencies
npm install

# Build the project (if applicable)
npm run build

# Run the server (stdio transport, single-user)
FIZZY_ACCESS_TOKEN="your-token-here" npm run start

Verification:

fizzy-mcp --help

Note: If you intend to deploy to Cloudflare Workers or other environments, refer to the deployment-specific guidance in the project documentation.

Tips and considerations:

• Environment variables: FIZZY_ACCESS_TOKEN is required for stdio transport; MCP_AUTH_TOKEN may be used for additional server-side authentication in multi-user setups.
• Transport selection: Use stdio for local development and IDE integrations; use HTTP (Streamable) for production or multi-user deployments; SSE is deprecated and not recommended for new deployments.
• Token management: Treat Fizzy access tokens as secrets. Do not hard-code tokens in shared configuration files.
• IDE integration: The provided example mcp.json integrates with Cursor; adapt similarly for other IDEs by pointing to the Fizzy MCP server and supplying the necessary token in env.
• Troubleshooting: If you encounter 5xx or timeouts, enable retry logic and ensure your Fizzy token has appropriate permissions.
• API coverage: The server exposes a full set of Fizzy tools; consult the Fizzy API docs linked in the README for details on available endpoints and usage patterns.