blocfeed-mcp

MCP (Model Context Protocol) server for BlocFeed — access user feedbacks, bugs, and issues directly from your AI coding assistant.

Works with Claude Code, Cursor, Windsurf, VS Code Copilot, OpenAI Codex CLI, and any MCP-compatible client.

What it does

Once connected, your AI assistant gets 9 tools to interact with your BlocFeed projects:

| Tool | What it does | |------|-------------| | blocfeed_select_project | Select which project to work with — sets it once, used by all other tools | | blocfeed_list_projects | List all projects you own or are a member of | | blocfeed_list_feedbacks | List/filter user feedback (by status, category, priority, sentiment, component) | | blocfeed_get_feedback | Full detail — page URL, component, console errors, network failures, AI analysis | | blocfeed_list_issues | List issues (clustered feedback patterns) with counts | | blocfeed_get_issue | Issue detail + the actual user messages that reported it | | blocfeed_update_issue | Mark issues as acknowledged / resolved / ignored, or assign them | | blocfeed_update_feedback | Mark individual feedback items as resolved | | blocfeed_list_areas | List feature areas (e.g. Checkout, Settings) with problem counts |

Project scoping

The MCP server is project-scoped — you select which project to work with, and all tools use it automatically. Two ways to set the active project:

Option A: Pre-configure via env var (recommended for per-project repos)

Set BLOCFEED_PROJECT_ID in your MCP config — the AI skips project selection entirely and works with your project immediately:

{
  "mcpServers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

Option B: Runtime selection

If BLOCFEED_PROJECT_ID isn't set, the AI calls blocfeed_select_project to choose a project. If you only have one project, it's auto-selected.

Example workflow:

You:    "Show me all open bugs from BlocFeed"
Claude: [calls blocfeed_select_project] → auto-selects your project
Claude: [calls blocfeed_list_issues with status=new] → shows 12 issues (no project_id needed!)

You:    "Get details on issue #5"
Claude: [calls blocfeed_get_issue] → shows component, user messages, console errors

You:    "Fix it and mark it resolved"
Claude: [reads your code, applies the fix, then calls blocfeed_update_issue status=resolved]

Prerequisites

1. Generate a BlocFeed API Key

1. Go to your BlocFeed dashboard: blocfeed.com/dashboard/settings
2. Scroll to the "Developer API Keys" section
3. Enter a name (e.g. "Claude Code") and click Generate
4. Copy the key immediately — it starts with bf_live_ and is only shown once

The key is scoped to your user account — one key gives access to all projects you own or are a member of.

2. Find your Project ID (optional but recommended)

1. Go to blocfeed.com/dashboard/settings
2. Your Project ID is shown in the project settings section
3. Use this to pre-configure BLOCFEED_PROJECT_ID in your MCP config

3. Store secrets in your environment

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export BLOCFEED_API_KEY="bf_live_your_key_here"

Then reload: source ~/.zshrc

This keeps the secret out of config files that get committed to git.

Setup by Client

Claude Code (CLI)

Claude Code picks up MCP servers from .mcp.json at your project root.

Per-project setup (recommended):

Create .mcp.json in your project root:

{
  "mcpServers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

BLOCFEED_PROJECT_ID is optional. If omitted, the AI will call blocfeed_select_project to pick one at runtime.

Verify it works:

1. Restart Claude Code (or start a new session)
2. Type: /mcp — you should see "blocfeed" listed with 9 tools
3. Ask: "Show me all open bugs from BlocFeed"

Cursor

Cursor supports MCP servers via its settings.

1. Open Cursor Settings → Features → MCP Servers
2. Click "Add new MCP Server"
3. Fill in:
   • Name: blocfeed
   • Type: command
   • Command: npx -y blocfeed-mcp
4. Add environment variables:
   • Key: BLOCFEED_API_KEY → Value: your bf_live_... key
   • Key: BLOCFEED_PROJECT_ID → Value: your project UUID (optional)

Or create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

Restart Cursor. The BlocFeed tools will appear in the AI assistant.

Windsurf

1. Open Windsurf Settings → MCP (or Cascade → MCP)
2. Click "Add Server"
3. Configure:
   • Name: blocfeed
   • Command: npx
   • Args: -y blocfeed-mcp
   • Environment: BLOCFEED_API_KEY → your key, BLOCFEED_PROJECT_ID → your project UUID (optional)

Or create ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

VS Code (GitHub Copilot)

VS Code supports MCP via the Copilot agent mode.

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

Then in VS Code:

1. Open the Copilot Chat panel
2. Switch to Agent mode (click the mode dropdown)
3. The BlocFeed tools will be available — ask "List my open bugs from BlocFeed"

OpenAI Codex CLI

Codex CLI supports MCP servers for tool access.

Create or edit ~/.codex/config.json:

{
  "mcpServers": {
    "blocfeed": {
      "command": "npx",
      "args": ["-y", "blocfeed-mcp"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

Restart Codex. Then:

> Show me all unresolved bugs from BlocFeed
> Fix issue #3 and mark it resolved

Any other MCP client

The blocfeed-mcp server uses the standard stdio transport. Any MCP-compatible client can connect using:

• Command: npx -y blocfeed-mcp
• Transport: stdio
• Required env var: BLOCFEED_API_KEY=bf_live_...
• Optional env var: BLOCFEED_PROJECT_ID=bf_your_project_id (skips project selection)
• Optional env var: BLOCFEED_API_URL=https://your-self-hosted-instance.com

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BLOCFEED_API_KEY | Yes | — | Your BlocFeed developer API key (starts with bf_live_) | | BLOCFEED_PROJECT_ID | No | — | Pre-select a project by its blocfeed_id (e.g. bf_m5abc_...). When set, tools skip project selection and work immediately. Also accepts UUID. | | BLOCFEED_API_URL | No | https://blocfeed.com | API base URL (only needed for self-hosted instances) |

What you can ask

Here are example prompts that work with any AI assistant once connected:

Browsing feedback:

• "Show me all new bug reports from BlocFeed"
• "List high-priority feedback from the last week"
• "What feedback is there about the checkout page?"
• "Show me negative feedback about the SubmitButton component"

Investigating issues:

• "What are the top 5 most reported issues?"
• "Get details on issue #12 — what are users saying?"
• "Show me all issues related to mobile"
• "What console errors are associated with feedback #42?"

Fixing and resolving:

• "Fix issue #5 based on the user feedback, then mark it resolved"
• "Mark feedback #42 as acknowledged"
• "Assign issue #8 to john"
• "Resolve all feedback linked to issue #3"

Understanding your app:

• "Which areas of my app have the most bug reports?"
• "List all feature areas and their problem counts"
• "What components are causing the most negative feedback?"

Troubleshooting

"Invalid or missing API key"

• Make sure the key starts with bf_live_
• Check that the key hasn't been revoked in the dashboard
• Verify the env var name is exactly BLOCFEED_API_KEY
• Confirm the env var is set in your shell: echo $BLOCFEED_API_KEY

"No project selected"

• Set BLOCFEED_PROJECT_ID in your MCP config, or
• Ask the AI to call blocfeed_select_project first
• If you only have one project, it will be auto-selected

Tools not showing up

• Restart your AI client after adding the MCP config
• In Claude Code, run /mcp to check if the server is connected
• Check that npx is available in your terminal (which npx)
• Make sure .mcp.json is at the project root (not in a subdirectory)

"BLOCFEED_API_KEY environment variable is required"

• The env var isn't reaching the MCP server
• If using ${BLOCFEED_API_KEY} syntax, the variable must be exported in your shell profile
• Run echo $BLOCFEED_API_KEY to confirm it's set
• Some clients require a full restart (not just reload) after env changes

Connection timeout

• The server connects to https://blocfeed.com by default
• If you're behind a corporate proxy, you may need to configure HTTPS_PROXY
• For self-hosted instances, set BLOCFEED_API_URL

Development

git clone <repo-url>
cd blocfeed-mcp
npm install
npm run build

# Test locally
BLOCFEED_API_KEY=bf_live_... node dist/index.js

# Test with project scoping
BLOCFEED_API_KEY=bf_live_... BLOCFEED_PROJECT_ID=uuid node dist/index.js

# Watch mode for development
npm run dev

Testing with Claude Code locally

For local development, point to your local build instead of the published package.

Create .mcp.json in your test project:

{
  "mcpServers": {
    "blocfeed": {
      "command": "node",
      "args": ["/absolute/path/to/blocfeed-mcp/dist/index.js"],
      "env": {
        "BLOCFEED_API_KEY": "${BLOCFEED_API_KEY}",
        "BLOCFEED_PROJECT_ID": "bf_your_project_id"
      }
    }
  }
}

API Reference

The MCP server calls these BlocFeed REST API endpoints under the hood:

| Endpoint | Method | Purpose | |----------|--------|---------| | /api/v1/projects | GET | List user's projects (owner + member) | | /api/v1/feedbacks?project_id=... | GET | List feedbacks with filters + pagination | | /api/v1/feedbacks/:id | GET | Get feedback detail | | /api/v1/feedbacks/:id | PATCH | Update feedback status | | /api/v1/issues?project_id=... | GET | List issues with filters + pagination | | /api/v1/issues/:id | GET | Get issue detail + linked feedbacks | | /api/v1/issues/:id | PATCH | Update issue status or assignee | | /api/v1/areas?project_id=... | GET | List areas with stats |

All endpoints require Authorization: Bearer bf_live_... header. List endpoints require project_id query parameter.

License

MIT