# @feedbug/mcp

[![npm version](https://img.shields.io/npm/v/@feedbug/mcp.svg)](https://www.npmjs.com/package/@feedbug/mcp)
[![license](https://img.shields.io/npm/l/@feedbug/mcp.svg)](https://www.npmjs.com/package/@feedbug/mcp)
[![feedbug-mcp MCP server](https://glama.ai/mcp/servers/joffreyBerrier/feedbug-mcp/badges/score.svg)](https://glama.ai/mcp/servers/joffreyBerrier/feedbug-mcp)

**Visual bug reports your AI agent can actually fix.**

[Feedbug](https://feedbug.app) lets your testers report bugs by clicking on them. Each report captures a screenshot, the console logs, the failed network requests, a session replay, and the **HTML/DOM context** of the element they clicked, then opens an issue in your **Linear** project or your **GitHub** repository automatically. When a code source is connected, the issue also carries a link to the source file the bug most likely came from.

This MCP server plugs that data straight into your AI coding agent (Claude Code, Cursor, Windsurf, VS Code). The agent reads the bug, gets the exact CSS selector and component path, traces it to the source file, proposes the patch, and marks the bug resolved.

Full write-up of the product side: [feedbug.app/mcp-bug-tracking](https://feedbug.app/mcp-bug-tracking).

> Point at the bug. Ship the fix.

## Quick start

```bash
npx @feedbug/mcp init
```

The installer asks for your client and your project key, then writes the config for you. Non-interactive:

```bash
npx @feedbug/mcp init --client claude pk_your_project_key
```

Supported clients: `claude` (Claude Code), `cursor`, `windsurf`. Grab your project key (`pk_...`) from your project page on [feedbug.app](https://feedbug.app).

Restart your client and the tools are live.

## Manual configuration

Add this to your client's MCP config (`.mcp.json`, `.cursor/mcp.json`, `.windsurf/mcp.json`, etc.):

```json
{
  "mcpServers": {
    "feedbug": {
      "command": "npx",
      "args": ["-y", "@feedbug/mcp"],
      "env": {
        "FEEDBUG_API_URL": "https://api.feedbug.app",
        "FEEDBUG_PROJECT_KEY": "pk_your_project_key"
      }
    }
  }
}
```

## Run with Docker

```bash
docker build -t feedbug-mcp .
```

```json
{
  "mcpServers": {
    "feedbug": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "FEEDBUG_PROJECT_KEY", "feedbug-mcp"],
      "env": {
        "FEEDBUG_PROJECT_KEY": "pk_your_project_key"
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `FEEDBUG_PROJECT_KEY` | Yes | none | Your project key (`pk_...`), from the Feedbug dashboard. |
| `FEEDBUG_API_URL` | No | `https://api.feedbug.app` | Override the API base URL (self-hosting / staging). |

## Tools

Every tool accepts either the feedback UUID or the tracker identifier (e.g. `PRE-13` on Linear, `owner/repo#42` on GitHub).

| Tool | What it does |
| --- | --- |
| `feedbug_list_bugs` | List reported bugs (filter by status or page URL). |
| `feedbug_get_bug` | Full details: screenshot, viewport, user agent, HTML context. |
| `feedbug_get_html_context` | DOM context of the clicked element: CSS selector path, framework component path (Vue/React/Angular/Svelte), attributes, ancestors, siblings. This is what lets the agent find the source. |
| `feedbug_get_diagnostics` | Browser diagnostics: page URL, viewport, user agent, reporter. |
| `feedbug_get_replay` | Session replay URL (last 30 seconds before the report). |
| `feedbug_add_comment` | Add a comment to the bug's Linear issue. |
| `feedbug_resolve_bug` | Mark a bug resolved once it's fixed. |

## How it works

When a tester clicks a bug, the Feedbug widget snapshots the DOM around the clicked element: the CSS selector path, the framework component name when detectable, the element's attributes and text, plus its ancestors and siblings. That snapshot travels with the Linear ticket.

Through this MCP server, your agent reads that context and maps the bug to the exact file and line, instead of guessing from a vague "it's broken on the dashboard" description.

## Links

- Product: [feedbug.app](https://feedbug.app)
- API: `https://api.feedbug.app`

## License

MIT