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
