hex-dashboard-mcp

MCP server for building and maintaining Hex notebooks from Claude Code. Wraps the Hex API with design-system-aware chart injection, notebook diagnostics, and full cell lifecycle management.

What it does

18 tools across five categories:

Cell management — read, create, update, and delete cells (CODE, SQL, MARKDOWN). Supports positional insertion and label-based identification.

Run management — trigger runs, poll status, cancel, view history. run_and_wait blocks until completion so the published app updates automatically without manual refresh.

Chart injection — inject_plotly_chart, inject_pydeck_map, and inject_html_component write fully styled code into cells using a built-in dark design system (Inter font, indigo accent palette, dark surfaces). KPI cards, section headers, and alert banners are templated.

Diagnostics — diagnose_notebook cross-references cell sources with run errors to surface root causes. inspect_filter_behavior reproduces failures with specific filter inputs.

Design system — get_design_system returns all tokens (colors, fonts, chart defaults). apply_workspace_palette sets the chart color sequence workspace-wide.

Related MCP server: Claude Code Toolkit

Setup

Requires Python 3.11+ and a Hex API token.

python -m venv .venv
.venv/bin/pip install fastmcp httpx

Claude Code Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hex-dashboard": {
      "command": "/path/to/hex-dashboard-mcp/.venv/bin/python",
      "args": ["/path/to/hex-dashboard-mcp/server.py"],
      "env": {
        "HEX_API_KEY": "your_hex_api_key",
        "HEX_API_URL": "https://app.hex.tech/api/v1"
      }
    }
  }
}

Claude Code CLI

claude mcp add --scope user --transport stdio hex-dashboard \
  /path/to/hex-dashboard-mcp/.venv/bin/python /path/to/hex-dashboard-mcp/server.py

Set HEX_API_KEY and HEX_API_URL in your shell environment.

Using with the Hex CLI

The official Hex CLI (brew install hex-inc/hex-cli/hex) complements this MCP well. Use each where it's strongest:

Rule of thumb: reading = CLI, writing/styling = MCP.

Skill file

CLAUDE.md contains agent instructions for Claude Code — the design system spec, workflow guidance, troubleshooting playbook, and tool selection rules. Install it as a Claude Code skill or place it alongside the server for automatic pickup.

Tools reference