Havoc MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like Claude Desktop to query case data, search by client name, and access firm analytics from Havoc.

Features

• Search Cases: Find cases by client name with relevance scoring
• List Cases: Browse recent cases with optional filtering by status
• Get Case Details: Retrieve full case information including key facts, transcription, and attachments
• Analytics: Get firm-wide statistics on case volumes, types, and intake specialist performance

Quick Start

1. Get Your API Key

1. Log into Havoc
2. Go to Settings > External Integrations
3. Create a new integration and copy the API key

2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "havoc": {
      "command": "npx",
      "args": ["-y", "havoc-mcp-server"],
      "env": {
        "HAVOC_API_KEY": "hvk_live_your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

4. Start Using It

Ask Claude questions like:

• "Find the case for Maria Rodriguez"
• "How many cases did we get this month?"
• "Show me recent personal injury cases"
• "Get details for case CA7f8e9d..."
• "Who's handled the most intakes this week?"

Available Tools

havoc_search_cases

Search for cases by client name. This is the primary tool for finding specific cases.

Parameters:

• query (required): Client name to search for
• limit (optional): Maximum results (default: 10, max: 50)
• response_format (optional): "markdown" or "json" (default: "markdown")

Example prompts:

• "Find the case for John Smith"
• "Look up Maria Rodriguez's case"
• "Search for cases with Garcia"

havoc_list_cases

List recent cases with optional filtering.

Parameters:

• limit (optional): Maximum cases to return (default: 20, max: 100)
• cursor (optional): Pagination cursor for next page
• status (optional): Filter by status (e.g., "awaiting_approval", "follow_up")
• response_format (optional): "markdown" or "json" (default: "markdown")

Example prompts:

• "Show me the 10 most recent cases"
• "List cases awaiting approval"
• "Get the next page of cases"

havoc_get_case

Get full details for a specific case.

Parameters:

• case_id (required): The unique case identifier
• response_format (optional): "markdown" or "json" (default: "markdown")

Example prompts:

• "Get details for case CA7f8e9d0c1b2a..."
• "Show me the full case information"

havoc_get_analytics

Get firm-wide statistics and trends.

Parameters:

• range (optional): Time range - "today", "yesterday", "thisWeek", "thisMonth", "last6Months", or "allTime" (default: "thisMonth")
• response_format (optional): "markdown" or "json" (default: "markdown")

Example prompts:

• "How many cases this month?"
• "What's our case breakdown by type?"
• "Who's handled the most intakes this week?"
• "Show me analytics for last 6 months"

Local Development

Prerequisites

• Node.js 18+
• npm or pnpm

Setup

cd mcp/havoc-mcp-server
npm install

Build

npm run build

Run locally

HAVOC_API_KEY=your_key_here npm start

Development with watch mode

HAVOC_API_KEY=your_key_here npm run dev

Testing with Claude Desktop (local build)

Update your Claude Desktop config to use the local build:

{
  "mcpServers": {
    "havoc": {
      "command": "node",
      "args": ["/path/to/mcp/havoc-mcp-server/dist/index.js"],
      "env": {
        "HAVOC_API_KEY": "hvk_live_your_api_key_here"
      }
    }
  }
}

Troubleshooting

"HAVOC_API_KEY environment variable is not set"

Make sure you've added the env section to your Claude Desktop config with your API key.

"Invalid API key"

Double-check that your API key is correct and the integration is enabled in Havoc Settings.

"Rate limit exceeded"

The API has rate limits. Wait a moment and try again, or contact your administrator to increase the limit.

Server not appearing in Claude Desktop

1. Make sure the config file is valid JSON
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for errors

API Permissions

The MCP server uses the permissions configured for your integration:

• read:cases - Basic case information (always included)
• read:key_facts - Key facts table and story summary
• read:transcription - Full call transcription
• read:intake_form - Intake form responses
• read:attachments - Attachment URLs

Configure these in Havoc Settings > External Integrations.

License

MIT