# Feedbucket MCP Server
A Model Context Protocol (MCP) server that lets AI assistants (Claude Code, Cursor) manage website feedback from [Feedbucket](https://feedbucket.app).
> **Beta Software**: This project is in beta. Use at your own risk. Please report issues on [GitHub](https://github.com/swiftcomza/feedbucket-mcp/issues).
## Prerequisites
Before installing this MCP server, make sure you have:
1. A [Feedbucket](https://feedbucket.app) account
2. Feedbucket installed on your website
3. Protected mode enabled (recommended):
- Go to [Widget Settings](https://dashboard.feedbucket.app/projects/YOUR_PROJECT_ID/settings/widget)
- Set "Trigger Feedbucket using a query string" to **Yes**
- Save settings and copy your secret key
## Quick Start
### 1. Install from npm
```bash
npm install -g feedbucket-mcp
```
### 2. Run the setup wizard
```bash
# 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:
```bash
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)
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
npm run setup -- https://your-website.com YOUR_SECRET --extract
```
### Full help
```bash
npm run setup -- --help
```
---
## Manual Configuration
If you prefer to configure manually:
### Claude Code
Add to `.mcp.json` in your project root:
```json
{
"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:
```bash
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:
```json
{
"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
```bash
# 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
