Skip to main content
Glama
Sign In
hex-dashboard-mcp

hex-dashboard-mcp

by richardggxcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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: Modal MCP

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:

Task

Tool

List projects, cells, runs

hex CLI (--json | jq)

Quick status checks

hex CLI

Create/update/delete cells

MCP

Inject styled charts, maps, HTML

MCP

Run + auto-poll after edits

MCP (run_and_wait)

Diagnose failures

MCP (diagnose_notebook)

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

Tool

Description

list_projects

List workspace projects

get_project

Project details + all cells

get_cell_source

Read a cell's source

create_cell

Add a new cell (CODE/SQL/MARKDOWN)

update_cell_source

Write to an existing cell

delete_cell

Remove a cell

run_project

Trigger a run

run_and_wait

Run and block until completion

get_run_status

Poll run status

get_run_history

Recent run history

cancel_run

Cancel a running execution

diagnose_notebook

Full diagnostic sweep

inspect_filter_behavior

Test specific filter combinations

inject_plotly_chart

Write a styled Plotly chart

inject_pydeck_map

Write a styled PyDeck map

inject_html_component

Write KPI cards, headers, banners

get_design_system

Return design tokens

apply_workspace_palette

Set workspace chart colors

Available Tools

18 tools
apply_workspace_paletteA

Apply the design system color palette to the Hex workspace custom styling. This sets the active chart color palette for all Chart cells in the workspace. Requires admin permissions.

Inputs: project_id (required). Returns: result

cancel_runB

Cancel a running Hex project run.

Inputs: run_id (required), project_id (required). Returns: result

create_cellA

Create a new cell in a Hex project.

cell_type: CODE | SQL | MARKDOWN source: the cell's source code / SQL / markdown content label: optional display label for the cell insert_after_cell_id: optional cell ID to insert after (otherwise appends to end) data_connection_id: required for SQL cells — the Hex data connection UUID

Inputs: source (required), cell_type (required), project_id (required), label, +2 more. Returns: result

delete_cellA

Delete a cell from a Hex project. Use with caution — this is irreversible. Always get_project() first to confirm the cell ID and contents before deleting.

Inputs: cell_id (required). Returns: result

diagnose_notebookA

Full diagnostic sweep of a Hex notebook.

  • Reads all cell sources

  • Pulls the most recent (or specified) run's error details

  • Identifies which cells failed and surfaces the error trace

  • Flags common issues: filter edge cases, missing variables, data type mismatches, empty dataframes, schema drift

Use this whenever a notebook fails to load, shows blank charts, or behaves incorrectly when filters are applied.

Inputs: project_id (required), run_id. Returns: result

get_cell_sourceA

Read the full source code of a specific cell (Python, SQL, or HTML). Use this before updating to understand what's already there.

Inputs: cell_id (required), project_id (required). Returns: result

get_design_systemA

Return the active design system tokens (colors, fonts, chart defaults). Use this to stay consistent when writing custom chart code.

Inputs: no named parameters. Returns: result

get_projectA

Get full details of a Hex project including all cells with their type, source, and position. Use this before editing to understand the current notebook structure.

Inputs: project_id (required). Returns: result

get_run_historyB

Get recent run history for a project. Useful for spotting patterns in recurring failures (specific filters, specific times, etc).

Inputs: project_id (required), limit. Returns: result

get_run_statusA

Poll the status of a project run. Status values: PENDING, RUNNING, COMPLETED, ERRORED, KILLED, UNABLE_TO_ALLOCATE_KERNEL. Check elapsedTime and any trace/error details on ERRORED runs.

Inputs: run_id (required), project_id (required). Returns: result

inject_html_componentA

Write a styled HTML component into a Hex HTML cell. These render in the published app with no Python needed.

component_type: kpi_row — row of metric cards (props: metrics=[{label, value, delta, delta_type}]) section_header — section title + subtitle (props: title, subtitle) data_table — styled HTML table (props: dataframe_var, max_rows) alert_banner — info/warning/error banner (props: message, level) divider — styled horizontal rule (props: label)

Inputs: props (required), cell_id (required), project_id (required), component_type (required), +1 more. Returns: result

inject_plotly_chartA

Write a fully styled Plotly chart into a Hex Python cell. Design system (dark theme, color palette, typography) is applied automatically.

chart_type: line | bar | scatter | area | histogram | box | heatmap | funnel | treemap dataframe_var: name of the DataFrame variable already defined in the notebook x_col / y_col: column names for axes color_col: optional column for series coloring extra_kwargs: any additional px.chart() keyword args as a string, e.g. 'barmode="group"' auto_run: if True, immediately triggers run_and_wait to push to app view

Inputs: x_col (required), y_col (required), cell_id (required), chart_type (required), +7 more. Returns: result

inject_pydeck_mapA

Write a styled PyDeck map into a Hex Python cell using the dark map style.

layer_type: ScatterplotLayer | HexagonLayer | H3HexagonLayer | ColumnLayer | ArcLayer | PathLayer | GeoJsonLayer color_col: column with pre-computed [R, G, B] or [R, G, B, A] values. If omitted, uses accent color. elevation_col: column for 3D height (ColumnLayer / HexagonLayer) auto_run: if True, triggers run_and_wait to push to app view

Inputs: cell_id (required), lat_col (required), lon_col (required), project_id (required), +7 more. Returns: result

inspect_filter_behaviorA

Trigger a run with specific filter input values to diagnose why a particular filter combination causes incorrect data or blank charts.

Pass the filter widget names and values as filter_inputs dict. Example: {"date_range": "2024-01-01,2024-03-31", "region": "EMEA"}

The tool runs the project, waits for completion, and surfaces any errors specific to those inputs.

Inputs: project_id (required), filter_inputs (required). Returns: result

list_projectsA

List Hex projects in the workspace. Optionally filter by name substring. Returns project IDs, names, and app URLs needed for other tools.

Inputs: limit, search. Returns: result

run_and_waitA

Run a Hex project and poll until it completes or errors. This is the primary tool for pushing notebook changes to the app view — after updating cells, call this and the published app will reflect the new results automatically without any manual refresh.

Returns the final run status with error details if it failed.

Inputs: project_id (required), inputs, timeout_seconds. Returns: result

run_projectA

Trigger a Hex project run. Returns a run_id for status polling. Use run_and_wait instead if you want to block until completion.

Inputs: project_id (required), inputs. Returns: result

update_cell_sourceA

Write new source code to a cell (Python, SQL, or Markdown). cell_type: CODE | SQL | MARKDOWN (default CODE). Used to wrap source in the correct API structure. After updating cells, call run_and_wait to push changes to the app view. The published app refreshes automatically when a run completes — no manual page refresh needed.

Inputs: source (required), cell_id (required), project_id (required), cell_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes: project listing, cell editing, run management, and chart injection. Some overlap exists between run_project and run_and_wait (both trigger runs), and between diagnose_notebook and inspect_filter_behavior (both diagnose issues), but descriptions clarify the differences well.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern in snake_case (e.g., get_design_system, list_projects, update_cell_source, cancel_run). The consistent style makes the API predictable and easy to navigate.

    Tool Count4/5

    With 18 tools, the server is slightly heavy but still scoped appropriately for a dashboard/notebook MCP. Each tool covers a distinct aspect of the workflow, though a few (diagnostics and run variants) could potentially be consolidated without losing functionality.

    Completeness4/5

    The tool set covers the full cell lifecycle (read, create, update, delete), run management (trigger, poll, cancel, history), and common dashboard visualization injection (Plotly, PyDeck, HTML). Minor gaps include lack of project create/delete and no explicit cell listing tool (only via get_project), but these are workable.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers