Fizzy MCP Server

A Model Context Protocol (MCP) server for Fizzy — the project management tool by Basecamp.

🚀 Try it live: https://fizzy.fabric.pro/mcp

📖 Fizzy API Documentation: github.com/basecamp/fizzy/blob/main/docs/API.md

This MCP server allows AI assistants like Claude, Cursor, and GitHub Copilot to interact with your Fizzy boards, cards, and projects through natural language.

Table of Contents

• Features

• Transport Support

• Prerequisites

• Quick Start

• Installation

• Getting Your Fizzy Access Token

• Configuration

  • For Cursor IDE

  • For VS Code with GitHub Copilot

  • For Claude Desktop

  • For Other MCP-Compatible IDEs

• Running the Server

• Environment Variables

• Available Tools

• Example Prompts

• Troubleshooting

• FAQ

• API Reference

• Development

• Contributing

• License

Related MCP server: fizzy-mcp

Features

• Full Fizzy API Coverage: 53 tools covering Boards, Cards, Card Actions, Pins, Comments, Reactions, Steps, Columns, Tags, Users, and Notifications

• Multiple Transport Protocols: Stdio (CLI/IDE), HTTP (Streamable), and SSE (deprecated)

• Multi-User Support: HTTP and SSE transports support multiple users with per-user authentication

• Flexible Deployment: Run locally (Node.js) or deploy globally (Cloudflare Workers)

• IDE Integration: Works with Cursor, VS Code, Claude Desktop, and other MCP-compatible tools

• Robust Error Handling: Structured error classes with detailed error messages

• Automatic Retries: Exponential backoff retry logic for transient failures (5xx errors, timeouts, network issues)

• Request Timeout: 30-second default timeout to prevent hanging requests

• ETag Caching: Automatic HTTP caching using ETags to reduce bandwidth and improve response times (as per Fizzy API caching spec)

• Fully Tested: Comprehensive test suite with 450+ test cases

Transport Support

The Fizzy MCP server supports multiple transport protocols depending on your deployment environment:

Transport Comparison

Deployment-Specific Support

Node.js Deployment

Supports all three transports:

• stdio: For single-user CLI/IDE integrations (recommended for local development)

• HTTP (Streamable): For multi-user web applications and production deployments (recommended)

• SSE: Deprecated, maintained for backwards compatibility only

Cloudflare Workers Deployment

Supports HTTP transport only:

• HTTP (Streamable): The only supported transport for Cloudflare Workers

• Why no stdio? Cloudflare Workers cannot spawn processes

• Why no SSE? SSE transport is deprecated and not supported on Cloudflare

Recommendations

• For IDE integrations (Cursor, VS Code, Claude Desktop): Use stdio transport

• For production deployments: Use HTTP (Streamable) transport

• For multi-user applications: Use HTTP (Streamable) transport

• For testing with MCP Inspector: Use HTTP (Streamable) transport

• Avoid SSE: The SSE transport is deprecated and will be removed in a future version

Authentication Models

stdio Transport (Single-User)

• Requires FIZZY_ACCESS_TOKEN environment variable

• One user per server instance

• Ideal for personal CLI/IDE use

HTTP/SSE Transports (Multi-User)

• Each user provides their own Fizzy Personal Access Token via Authorization: Bearer <token> header

• Multiple users can connect simultaneously

• Each session is isolated with its own FizzyClient instance

• Sessions timeout after 30 minutes of inactivity

• Optional server-level authentication via MCP_AUTH_TOKEN environment variable (clients send it in the X-MCP-Auth-Token header)

Prerequisites

• Node.js 22 or higher

• A Fizzy account with API access

Quick Start

Get up and running in 3 steps:

1. Get your Fizzy access token from app.fizzy.do → Profile → API → Personal access tokens

2. Run with npx (no installation needed):

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

3. Configure your IDE (e.g., Cursor):

   • Open Cursor Settings → Features → MCP Servers

   • Click "Edit in mcp.json" and add:

   {
     "mcpServers": {
       "fizzy": {
         "command": "npx",
         "args": ["-y", "fizzy-mcp"],
         "env": {
           "FIZZY_ACCESS_TOKEN": "your-token-here"
         }
       }
     }
   }

   • Restart Cursor

That's it! You can now ask your AI assistant to interact with Fizzy.

💡 Note: This Quick Start uses stdio transport for single-user IDE integration. For production deployments or multi-user applications, see the HTTP Transport section.

For detailed installation options and configuration, see the sections below.

Installation

Option 1: Install from npm (recommended)

npm install -g fizzy-mcp

The fizzy-mcp command will be available globally.

Option 2: Use with npx (no installation required)

npx fizzy-mcp --help

Option 3: Install from source

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

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (makes `fizzy-mcp` command available)
npm link

To verify the installation:

fizzy-mcp --help

Getting Your Fizzy Access Token

1. Log in to your Fizzy account

2. Go to your Profile (click your avatar)

3. Navigate to the API section

4. Click on Personal access tokens

5. Click Generate new access token

6. Give it a description and select permissions:

   • Read: For read-only access

   • Read + Write: For full access (recommended)

7. Copy and save your token securely

⚠️ Important: Keep your access token secret! Anyone with your token can access your Fizzy account.

Configuration

For Cursor IDE

💡 Note: The root mcp.json in this repository is a manifest for the Cursor Plugin marketplace. For manual setup in your local ~/.cursor/mcp.json, substitute your actual token as shown below (do not copy the literal ${FIZZY_ACCESS_TOKEN}).

Cursor supports two connection methods: stdio (local process) and HTTP (remote server).

Option 1: Stdio Transport (Local Process - Recommended for Personal Use)

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Search for "MCP" or navigate to Features > MCP Servers

3. Click Edit in mcp.json or manually edit ~/.cursor/mcp.json:

Using npx (recommended):

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-mcp"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "your-fizzy-access-token-here"
      }
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "fizzy": {
      "command": "fizzy-mcp",
      "env": {
        "FIZZY_ACCESS_TOKEN": "your-fizzy-access-token-here"
      }
    }
  }
}

4. Restart Cursor for changes to take effect

Option 2: HTTP Transport (Remote Server - For Shared/Production Deployments)

Use this method to connect to a remote Fizzy MCP server (e.g., deployed on Cloudflare Workers or a shared Node.js server).

1. Open Cursor Settings and edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fizzy": {
      "url": "https://fizzy.fabric.pro/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_FIZZY_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

For local HTTP server:

{
  "mcpServers": {
    "fizzy": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_FIZZY_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

2. Restart Cursor for changes to take effect

💡 Tip: Use the live server at https://fizzy.fabric.pro/mcp to try Fizzy MCP without running your own server!

For VS Code with GitHub Copilot

Option 1: Stdio Transport (Local Process)

Create or edit .vscode/mcp.json in your workspace (or global settings):

{
  "mcpServers": {
    "fizzy": {
      "command": "npx",
      "args": ["-y", "fizzy-mcp"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "your-fizzy-access-token-here"
      }
    }
  }
}

Option 2: HTTP Transport (Remote Server)

{
  "mcpServers": {
    "fizzy": {
      "url": "https://fizzy.fabric.pro/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_FIZZY_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

For Claude Desktop

Claude Desktop supports stdio transport only.

Edit your Claude Desktop configuration file:

• 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", "fizzy-mcp"],
      "env": {
        "FIZZY_ACCESS_TOKEN": "your-fizzy-access-token-here"
      }
    }
  }
}

For Other MCP-Compatible IDEs

Most MCP-compatible IDEs support HTTP transport. Use this configuration pattern:

{
  "mcpServers": {
    "fizzy": {
      "url": "https://fizzy.fabric.pro/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_FIZZY_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Replace https://fizzy.fabric.pro/mcp with your own server URL if you're self-hosting.

Running the Server

Stdio Transport (default - for IDE integration)

# Using npx
FIZZY_ACCESS_TOKEN="your-token" npx fizzy-mcp

# If installed globally
FIZZY_ACCESS_TOKEN="your-token" fizzy-mcp

SSE Transport (for web clients)

# Start the server (no FIZZY_ACCESS_TOKEN needed - users provide their own)
npx fizzy-mcp --transport sse --port 3000

# Endpoints:
#   SSE: http://localhost:3000/sse
#   Messages: http://localhost:3000/messages

Connecting clients:

# Each user provides their own Fizzy token via Authorization header
curl -H "Authorization: Bearer YOUR_FIZZY_TOKEN" \
     http://localhost:3000/sse

Streamable HTTP Transport (for production)

# Start the server (no FIZZY_ACCESS_TOKEN needed - users provide their own)
npx fizzy-mcp --transport http --port 3000

# Endpoints:
#   MCP: http://localhost:3000/mcp
#   Health: http://localhost:3000/health

Connecting clients:

# Each user provides their own Fizzy token via Authorization header
curl -X POST \
     -H "Authorization: Bearer YOUR_FIZZY_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
     http://localhost:3000/mcp

Cloudflare Workers (for edge deployment)

Deploy to Cloudflare Workers for global distribution with near-zero cold starts:

# Install dependencies
npm install

# Login to Cloudflare
npx wrangler login

# Deploy
npm run cf:deploy

Important Notes:

• Cloudflare Workers only supports HTTP transport (no stdio or SSE)

• Multi-user authentication: Each user provides their own Fizzy token via Authorization: Bearer <token> header

• No FIZZY_ACCESS_TOKEN needed: Unlike stdio transport, Cloudflare deployment uses per-user tokens

• Durable Objects: Sessions are managed using Cloudflare Durable Objects for persistence

See the Cloudflare Deployment Guide for detailed instructions.

Environment Variables

Core Configuration

HTTP/SSE Transport Security

When using HTTP or SSE transports, additional security options are available:

Origins are matched exactly. The one convenience is loopback: an entry written without a port (http://localhost) matches any port on that same scheme and hostname, while an entry that pins a port (http://localhost:3000) matches only that port — and never a different loopback hostname or scheme.

Multi-User Support:

SSE and HTTP transports support multiple users simultaneously:

• Each user provides their own Fizzy Personal Access Token via Authorization: Bearer <token> header

• Each session is isolated with its own FizzyClient instance

• Users cannot access each other's data

• Sessions timeout after 30 minutes of inactivity

Security Model:

• Localhost binding (default): Server binds to 127.0.0.1, preventing remote access

• CORS origins: Controls which web origins can connect (default: all)

• User Authentication: Each user provides their own Fizzy token via Authorization header

• Client Authentication: Optional bearer token to authenticate MCP clients connecting to this server

# Basic usage (binds to localhost, allows all CORS origins)
# Users provide their own tokens via Authorization header
npx fizzy-mcp --transport http --port 3000

# Restrict CORS to specific origins
MCP_ALLOWED_ORIGINS="http://localhost:3000,https://myapp.com" \
npx fizzy-mcp --transport http --port 3000

# Enable Client Authentication (require MCP clients to present a shared token)
# Clients then send it as: X-MCP-Auth-Token: my-secret-token
MCP_AUTH_TOKEN="my-secret-token" \
npx fizzy-mcp --transport http --port 3000

# For Docker/remote access (use with restricted origins and client auth)
MCP_BIND_ALL_INTERFACES=true \
MCP_ALLOWED_ORIGINS="https://myapp.com" \
MCP_AUTH_TOKEN="my-secret-token" \
npx fizzy-mcp --transport http --port 3000

⚠️ Authentication Types:

• User Authentication (via Authorization header): Required for SSE/HTTP transports. Each user provides their own Fizzy Personal Access Token. On the Cloudflare Worker, Authorization is only ever read as this token; the Node transports also read it as the client token in the compatibility mode described below, which is why that mode should not be used for new deployments.

• Client Authentication (MCP_AUTH_TOKEN, via the X-MCP-Auth-Token header): Optional. Authenticates MCP clients (like IDE extensions) connecting to this server. Sent as the bare token, with no Bearer prefix, so it never competes with the Fizzy token above:

  {
    "headers": {
      "Authorization": "Bearer YOUR_FIZZY_PERSONAL_ACCESS_TOKEN",
      "X-MCP-Auth-Token": "YOUR_MCP_AUTH_TOKEN"
    }
  }

  For compatibility, the Node HTTP/SSE transports also still accept the client token as Authorization: Bearer <MCP_AUTH_TOKEN> when no X-MCP-Auth-Token header is present. That mode consumes the header the per-user Fizzy token needs, so don't use it for new deployments. The Cloudflare Worker accepts X-MCP-Auth-Token only.

Note: For stdio transport, use FIZZY_ACCESS_TOKEN environment variable (single-user mode for CLI/IDE integrations).

Available Tools (54 total)

Identity & Accounts (2)

Boards (5)

Cards (6)

Card Actions (13)

Comments (5)

Reactions (3)

Steps / To-dos (4)

Columns (5)

Tags (1)

Users (4)

Notifications (4)

Attachments (2)

Attaching a file to a card or comment

fizzy_upload_file uploads the file and returns an attachment_html snippet. It does not attach anything by itself — every rich-text field already accepts HTML, so you include the snippet wherever you want the file to appear:

// 1. Upload. Use file_path locally, or base64_data anywhere.
{ "name": "fizzy_upload_file",
  "arguments": { "account_slug": "123456", "file_path": "/tmp/screenshot.png" } }

// Returns:
// {
//   "attachable_sgid": "eyJfcmFpbHMi...",
//   "filename": "screenshot.png",
//   "content_type": "image/png",
//   "byte_size": 8124,
//   "attachment_html": "<action-text-attachment sgid=\"eyJfcmFpbHMi...\"></action-text-attachment>"
// }

// 2. Reference it in any rich-text field — a comment body here, but a card
//    description works the same way.
{ "name": "fizzy_create_comment",
  "arguments": {
    "account_slug": "123456",
    "card_number": "42",
    "body": "<p>Steps to reproduce:</p><action-text-attachment sgid=\"eyJfcmFpbHMi...\"></action-text-attachment>"
  } }

Use attachment_html verbatim. It carries the blob's attachable_sgid, which is the only token ActionText resolves; a hand-built tag using some other signed id will save without error and then render as a broken-attachment placeholder.

File input: provide exactly one of file_path or base64_data.

file_path is accepted only on stdio, where the MCP client and the server are the same user, so the server reads nothing that user could not already read. The HTTP and SSE transports serve remote callers — honouring a path there would let a client read the server's disk — and Workers have no filesystem. Uploads are capped at 10 MB on both paths.

Reading an attachment that is already on a card

The API never reports attachments as data. They exist only as <action-text-attachment> markup inside the rich-text HTML — description_html on a card, body.html on a comment — and the plain-text rendering flattens each one to a bare [filename.png] with no URL. Reading one back is therefore two steps.

include_attachments is opt-in and changes nothing when omitted: without it, both tools return exactly the response they always did.

// 1. Ask for the structured metadata alongside the card.
{ "name": "fizzy_get_card",
  "arguments": { "account_slug": "1234567", "card_id": "42", "include_attachments": true } }

// Adds an "attachments" array to the usual card payload:
// [{
//   "filename": "screenshot.png",
//   "content_type": "image/png",
//   "byte_size": 204800,
//   "width": 1600,
//   "height": 900,
//   "signed_id": "eyJfcmFpbHMi...--1111...",
//   "url": "https://app.fizzy.do/1234567/rails/active_storage/blobs/redirect/...",
//   "preview_url": "https://app.fizzy.do/1234567/rails/active_storage/representations/redirect/...",
//   "preview_variation": "eyJfcmFpbHMi...--3333..."
// }]

// 2. Fetch it. Pass preview_variation as `variation` to get the resized
//    preview, which is what a model can usefully look at.
{ "name": "fizzy_get_attachment",
  "arguments": {
    "account_slug": "1234567",
    "signed_id": "eyJfcmFpbHMi...--1111...",
    "filename": "screenshot.png",
    "variation": "eyJfcmFpbHMi...--3333..."
  } }

PNG, JPEG, GIF and WebP come back as an MCP image block the model can see. Anything else — PDFs, archives, SVG, video — comes back as metadata with a note that it is not renderable, and its bytes are never downloaded.

fizzy_get_attachment takes no URL, by design. Fetching a caller-supplied URL with the account's access token attached would be a server-side request forgery carrying a credential, so the tool takes the blob's signed_id and rebuilds the address itself. Inlined images are capped at 3 MB — Base64 inflates by ~4/3 into the response — and an original over that is refused in favour of its preview rather than truncated.

The token is never sent to the storage host. ActiveStorage answers with a redirect to a signed storage URL, and that redirect is followed by hand: the Authorization header is attached only while the URL is still on the configured Fizzy origin, rather than trusting a runtime to strip credentials across origins.

Example Prompts

Once configured, you can ask your AI assistant things like:

• "Show me all my Fizzy boards"

• "What cards are on my Engineering board?"

• "Create a new card called 'Fix login bug' on the Engineering board"

• "What cards are assigned to me?"

• "Move the 'Design review' card to the 'Done' column"

• "Add a comment to the authentication card saying 'Ready for review'"

• "Attach this screenshot to card 42 as evidence"

• "Show me the screenshot attached to card 42"

• "Show me my unread notifications"

• "List all users in my account"

• "Create a new column called 'In Review' with blue color on the Engineering board"

Troubleshooting

"FIZZY_ACCESS_TOKEN environment variable is required"

Make sure you've set your access token in the MCP configuration's env section.

"fizzy-mcp: command not found"

• Use npx fizzy-mcp instead of fizzy-mcp

• Or install globally: npm install -g fizzy-mcp

Server not appearing in Cursor/VS Code

1. Restart the IDE after configuration changes

2. Check the path to the executable is correct

3. Verify Node.js is installed: node --version

4. Check Cursor's MCP logs for errors

"Fizzy API error: 404 Not Found"

• Verify your access token is valid

• Check that you're using the correct account slug

• Ensure you have permission to access the resource

Connection issues

Test your token directly:

curl -H "Authorization: Bearer your-token" \
     -H "Accept: application/json" \
     https://app.fizzy.do/my/identity.json

FAQ

How do I get started quickly?

See the Quick Start section above for a 3-step setup guide.

Is my Fizzy access token secure?

Your access token is stored in your local IDE configuration and is never sent anywhere except directly to Fizzy's API. When using HTTP/SSE transports, the token is used server-side only. Always keep your token secret and never commit it to version control.

Can I use this with multiple Fizzy accounts?

Yes! You can configure multiple MCP server instances in your IDE, each with a different access token. Just give them different names in the configuration (e.g., "fizzy-personal", "fizzy-work").

What's the difference between the transport modes?

• stdio (default): For single-user IDE integration (Cursor, VS Code, Claude Desktop). Communication happens via standard input/output. Requires FIZZY_ACCESS_TOKEN environment variable.

• http (Streamable HTTP): Recommended for production. Multi-user support with per-user authentication via Authorization headers. Runs an HTTP server with streamable endpoints and health checks. Supported on both Node.js and Cloudflare Workers.

• sse (Server-Sent Events): ⚠️ Deprecated - maintained for backwards compatibility only. Multi-user support but uses older protocol version (2024-11-05). Only supported on Node.js. Use HTTP transport instead.

Which transport should I use?

• For IDE integrations (Cursor, VS Code, Claude Desktop): Use stdio

• For production deployments: Use HTTP (Streamable)

• For multi-user applications: Use HTTP (Streamable)

• For testing with MCP Inspector: Use HTTP (Streamable)

• For Cloudflare Workers deployment: Use HTTP (Streamable) (only option)

How do I test with MCP Inspector?

MCP Inspector is a tool for testing MCP servers. Here's how to use it with Fizzy MCP:

1. Start the HTTP server:

npm run build
npm run start:http
# Server runs on http://localhost:3000

2. Launch MCP Inspector:

npx @modelcontextprotocol/inspector

3. Configure the connection:

• Transport: Select "HTTP"

• URL: http://localhost:3000/mcp

• Headers: Add Authorization: Bearer YOUR_FIZZY_TOKEN

4. Test the connection:

• Click "Connect"

• You should see the list of 47 available tools

• Try calling tools like fizzy_get_identity or fizzy_get_boards

Note: MCP Inspector does not support the deprecated SSE transport. Always use HTTP transport for testing.

Does this work offline?

No, the server requires an internet connection to communicate with Fizzy's API at app.fizzy.do.

How do I update to the latest version?

If using npx, it will automatically use the latest version. If installed globally, run npm update -g fizzy-mcp. If installed from source, run git pull && npm install && npm run build.

Can I create tags via the API?

No, tag creation is not available via the Fizzy API. However, you can use fizzy_toggle_card_tag which will create a tag if it doesn't exist when toggling it on a card.

What happens if I hit rate limits?

The server includes automatic retry logic with exponential backoff for rate limit errors (429 status). It will retry up to 3 times before failing.

How does ETag caching work?

The server automatically caches GET requests using ETags. When you request the same resource again, it sends the ETag to Fizzy's API. If the resource hasn't changed, Fizzy returns a 304 Not Modified response, saving bandwidth and improving speed.

Can I use this in production?

Yes! You have two options:

1. Self-hosted: Use the HTTP transport mode with proper security settings (MCP_AUTH_TOKEN, MCP_ALLOWED_ORIGINS, and consider MCP_BIND_ALL_INTERFACES for Docker deployments).

2. Cloudflare Workers: Deploy to the edge for global distribution, automatic scaling, and near-zero cold starts. See the Cloudflare Deployment Guide.

Where can I find the Fizzy API documentation?

Official Fizzy API docs: github.com/basecamp/fizzy/blob/main/docs/API.md

API Reference

This server implements all endpoints from the official Fizzy API Documentation:

Development

For contributors and developers:

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

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type checking
npm run typecheck

License

MIT

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass: npm test

5. Submit a pull request

Author

Created by Preetham Reddy