@flusterduck/mcp-server

Local stdio MCP server for Flusterduck. Exposes your site's confusion scores, UX issues, alerts, deploys, session timelines, recommendations, and raw data to AI assistants over the Model Context Protocol.

Run it on your machine to connect Claude Desktop (or any MCP-compatible client) to your Flusterduck data without opening a public endpoint.

Run it

No install required:

npx -y @flusterduck/mcp-server

Or install the flusterduck-mcp binary globally:

npm install -g @flusterduck/mcp-server
flusterduck-mcp

The server communicates over stdio and is meant to be launched by an MCP client rather than used interactively.

Configuration

Configuration is read from environment variables:

| Variable | Required | Description | |---|---|---| | FLUSTERDUCK_MCP_KEY | yes | Your Flusterduck MCP key (fd_mcp_...). FLUSTERDUCK_API_KEY is accepted as an alias. | | FLUSTERDUCK_SITE_ID | yes | The site (UUID) whose data you want to expose. | | FLUSTERDUCK_ORG_ID | no | Org ID. Required only for the audit log, degradation, and webhook delivery tools. | | FLUSTERDUCK_API_URL | no | Override the Flusterduck query API base URL. Defaults to the hosted Flusterduck API. |

Use an MCP key (fd_mcp_) or a secret key (fd_sec_). Publishable keys (fd_pub_) are browser-only and will not authenticate against the query API. Write tools (issue/alert updates, alert-rule and annotation management) require a key with manage:write scope.

Claude Desktop configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "flusterduck": {
      "command": "npx",
      "args": ["-y", "@flusterduck/mcp-server"],
      "env": {
        "FLUSTERDUCK_MCP_KEY": "fd_mcp_...",
        "FLUSTERDUCK_SITE_ID": "your-site-id"
      }
    }
  }
}

Available tools

| Tool | Description | |---|---| | get_site_context | Full MCP snapshot for the configured site | | get_scores | Current page confusion scores | | get_page | Score history, issues, alerts, and elements for one page | | get_elements | Element-level friction summaries | | get_issues | UX issues, filtered by status | | get_issue | Single issue with evidence, sessions, and verification history | | get_alerts | Alerts, filtered by status | | list_alert_rules | Configured alert rules | | get_session_detail | Full event timeline for a session | | get_flows | Page-to-page flow edges from recent sessions | | get_trends | Score history over 1-90 days | | get_deploys | Deploys with confusion_before / confusion_after | | compare_pages | Side-by-side confusion comparison for two pages | | get_recommendations | Prioritized fix recommendations | | get_revenue_impact | Revenue impact estimates | | get_heuristics | Full friction heuristic catalog | | diagnose_journey_friction | High-friction path edges from recent sessions | | query_raw_rows | Raw rows from allowlisted tables | | download_events_csv | CSV export of raw events | | get_audit_log | Organization audit log (requires org ID) | | get_degradation | Active backend degradation events (requires org ID) | | get_webhook_deliveries | Outbound webhook delivery history (requires org ID) |

Write tools (require manage:write scope): update_issue, update_alert, add_annotation, create_alert_rule, update_alert_rule, delete_alert_rule.

Resources

| URI | Description | |---|---| | flusterduck://site/context | Current site context snapshot | | flusterduck://page/{path} | Detailed context for a specific page path |

Prompts

diagnose_page, triage_open_issues, post_deploy_check, investigate_session, weekly_summary — guided multi-step workflows for common UX investigations.

Programmatic usage

import { createFlusterduckMCPServer } from '@flusterduck/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createFlusterduckMCPServer({
  apiKey: process.env.FLUSTERDUCK_MCP_KEY!,
  siteId: process.env.FLUSTERDUCK_SITE_ID!,
  baseUrl: process.env.FLUSTERDUCK_API_URL ?? 'https://api.flusterduck.com',
});

const transport = new StdioServerTransport();
await server.connect(transport);

(c) Flusterduck. Proprietary. All rights reserved.