Feedbucket MCP Server

A Model Context Protocol (MCP) server that lets AI assistants (Claude Code, Cursor) manage website feedback from Feedbucket.

Beta Software: This project is in beta. Use at your own risk. Please report issues on GitHub.

Prerequisites

Before installing this MCP server, make sure you have:

A Feedbucket account
Feedbucket installed on your website
Protected mode enabled (recommended):
- Go to Widget Settings
- Set "Trigger Feedbucket using a query string" to Yes
- Save settings and copy your secret key

Quick Start

1. Install from npm

npm install -g feedbucket-mcp

2. Run the setup wizard

# For protected projects:
feedbucket-setup https://your-website.com YOUR_FEEDBUCKET_SECRET

# For public projects:
feedbucket-setup https://your-website.com

The setup script automatically:

Extracts the project ID from your website HTML
Fetches the private key from Feedbucket API
Configures Claude Code and Cursor

3. Restart your IDE

Restart Claude Code or Cursor to load the new MCP server.

4. Start using it

Ask your AI assistant:

"Show me unresolved feedback from Feedbucket"
"What's the feedback summary for this project?"
"Add a comment to feedback #12345 saying we've fixed this"

Alternative: Clone from GitHub

If you prefer to clone the repository:

git clone https://github.com/swiftcomza/feedbucket-mcp.git
cd feedbucket-mcp
npm install && npm run build
npm run setup -- https://your-website.com YOUR_FEEDBUCKET_SECRET

Available Tools

Tool	Description
`feedback_list`	List and filter feedback with smart summarization
`feedback_get`	Get full details of a specific feedback item
`feedback_stats`	Quick project overview (total, resolved, by type, recent activity)
`feedback_comment`	Add comments to feedback items
`feedback_resolve`	Mark feedback as resolved
`api_status`	Check API connection status

feedback_list

List feedback with powerful filtering:

Parameters:
- resolved (boolean): Filter by resolution status
- limit (number): Items to retrieve (default: 10, max: 50)
- offset (number): Skip items for pagination
- summary (boolean): Return condensed format (default: true)
- page_filter (string): Filter by page URL (partial match)
- reporter_filter (string): Filter by reporter name
- feedback_type (string): 'screenshot', 'video', or 'text'
- created_after (string): ISO date filter

feedback_get

Get complete details for a single feedback item:

Parameters:
- feedback_id (number, required): The feedback ID

Returns full text, all comments, attachments, browser/device info, and console logs.

feedback_stats

Get a quick project health overview:

Returns:
- Total feedback count
- Resolved vs unresolved breakdown
- Feedback by type (screenshot/video/text)
- Recent activity (7 days, 30 days)
- Top 5 pages with most feedback

feedback_comment

Add a comment to a feedback item:

Parameters:
- feedback_id (number, required): The feedback ID
- comment (string, required): Comment text
- reporter_name (string): Defaults to "Claude AI Assistant"
- reporter_email (string): Defaults to "claude@anthropic.com"
- resolve (boolean): Also resolve the feedback (default: false)

feedback_resolve

Mark a feedback item as resolved:

Parameters:
- feedback_id (number, required): The feedback ID

Setup Options

Automatic Setup (recommended)

# Protected project - provide URL and secret
npm run setup -- https://your-website.com YOUR_SECRET

# Public project - just the URL
npm run setup -- https://your-website.com

Manual Project ID (if auto-detection fails)

# With project ID only (public)
npm run setup -- --project-id tMbUCuQ4FeFJVViMEPlb

# With project ID and API key (protected)
npm run setup -- --project-id tMbUCuQ4FeFJVViMEPlb --api-key YOUR_SECRET

Configure only one IDE

# Claude Code only
npm run setup -- https://your-website.com YOUR_SECRET --claude

# Cursor only
npm run setup -- https://your-website.com YOUR_SECRET --cursor

Extract credentials without configuring

npm run setup -- https://your-website.com YOUR_SECRET --extract

Full help

npm run setup -- --help

Manual Configuration

If you prefer to configure manually:

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "feedbucket": {
      "command": "node",
      "args": ["/path/to/feedbucket-mcp/dist/index.js"],
      "env": {
        "FEEDBUCKET_PROJECT_ID": "your-project-id",
        "FEEDBUCKET_PRIVATE_KEY": "your-private-key",
        "FEEDBUCKET_API_KEY": "your-api-key"
      }
    }
  }
}

Or use the CLI:

claude mcp add feedbucket \
  -e FEEDBUCKET_PROJECT_ID="your-project-id" \
  -e FEEDBUCKET_PRIVATE_KEY="your-private-key" \
  -e FEEDBUCKET_API_KEY="your-api-key" \
  -- node /path/to/feedbucket-mcp/dist/index.js

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "feedbucket": {
      "command": "node",
      "args": ["/path/to/feedbucket-mcp/dist/index.js"],
      "env": {
        "FEEDBUCKET_PROJECT_ID": "your-project-id",
        "FEEDBUCKET_PRIVATE_KEY": "your-private-key",
        "FEEDBUCKET_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`FEEDBUCKET_PROJECT_ID`	Yes	Project ID from the `data-feedbucket` attribute
`FEEDBUCKET_PRIVATE_KEY`	Yes	Private key for commenting/resolving (auto-fetched by setup)
`FEEDBUCKET_API_KEY`	No*	API key for protected projects (`feedbucketKey` from URL)

*Required if your project uses query string protection.

Development

# Install dependencies
npm install

# Development mode (with hot reload)
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Build for production
npm run build

Architecture

This MCP server was reverse-engineered from the Feedbucket browser widget to provide:

Smart Summarization: Optimizes large datasets for AI consumption
Client-side Filtering: Reduces API calls by filtering locally
Full TypeScript: Strict mode with comprehensive types
Production Ready: Proper error handling and validation

API Endpoints Used

Method	Endpoint	Purpose
GET	`/projects/{id}`	Fetch project with all feedback
POST	`/feedback/{id}/comments`	Add comment to feedback
PUT	`/feedback/{id}/resolve`	Mark feedback as resolved

License

MIT