mviz

Generate beautiful static reports for ad hoc analysis. A Claude skill that turns compact JSON specs into professional HTML visualizations.

Why mviz?

The highest-value analysis in any company is point-in-time, highly contextual, and not reused once the decision is made.

Traditional BI tools optimize for reusability instead of usefulness. Useful analysis, the kind that drives critical decisions, needs something more:

• Fast iteration: Query data → visualize → refine → share
• AI-native workflow: Works seamlessly with Claude for data exploration
• Static output: Beautiful HTML/PDF reports, no infrastructure required
• Minimal tokens: Compact specs instead of verbose chart code

Instead of writing 50-100 lines of chart boilerplate, write a compact JSON spec that gets expanded into a full HTML artifact with ECharts.

Quick Start

1. Connect Your Database

Connect Claude to your data using an MCP server:

• MotherDuck MCP - Cloud data warehouse with DuckDB compatibility
• Local DuckDB MCP - Query local .duckdb files, Parquet, CSV, or S3 data

If you do not have a database available, you can also load CSV files directly, although the amount of data you can fit in context can be quite limiting.

2. Add the Skill

Claude Web or Desktop: Download mviz.skill and add it to your project knowledge.

Claude Code: Run npx add-skill matsonj/mviz or clone this repo and work from the directory.

3. Effective Use Tips

The best analysis follows four steps:

1. Build context — Get the data right. Query, filter, and explore until you understand what you're looking at.
2. Develop narrative — What's the story? What question are you answering? What pattern matters?
3. First pass on viz — Create an initial visualization. Don't overthink it.
4. Refine based on what doesn't work — Iterate. Change chart types, adjust formatting, add context.

Start by exploring your data with natural questions. Claude writes SQL queries behind the scenes and brings the results into context:

"Show me revenue by region for Q4"

"What are our top 10 customers by lifetime value?"

"Are there any anomalies in last month's sales data?"

Once you've built up context and are ready to visualize, tell Claude to "use mviz to report on this analysis". Claude generates a polished HTML report from the data you've explored.

4. Iterate

Refine your analysis by asking follow-up questions:

"Change that bar chart to a line chart"

"Drill into the APAC region—what's driving that spike?"

"Add a table showing the top 5 products by growth rate"

mviz Specific Guidance

mviz uses a 16-column grid.

"Make the bar chart wider"

"Show two charts side by side at size=[8,6] each"

"Make the KPIs smaller: size=[3,2] so 5 fit in a row"

By default, it will use size=auto to let mviz calculate appropriate dimensions based on your data.

[!TIP] There are more chart types available in the library than are included in the skill.md. You can tell Claude to look at the TypeScript source for more chart types if you really need them.

Each iteration builds on your existing context. When you're done, save the HTML or print to PDF.

Supported Chart Types

UI Components

File References (JSON and CSV)

Reference external files instead of embedding large JSON specs:

...