marzukia/charted

Quickstart
Or with pip:
That is the whole loop: pass a list of numbers, get back an image. No numpy, no
pandas, no config files.
> **Core principle:** charted itself has zero runtime dependencies. PNG export
> and MCP server support are opt-in extras that pull in their own dependencies,
> and the base library stays pure Python.
---
Gallery
Every chart type, rendered. Each image below was generated by charted itself
from the example script; the Quick Tour
shows the code behind each one.
| | | |
|---|---|---|
| **Bar** | **Column** | **Line** |
| **Scatter** | **Pie** | **Area** |
| **Radar** | **Box Plot** | **Histogram** |
| **Heatmap** | **Gantt** | **Bubble** |
| **Combo** | **Polar Area** | |
Sankey diagrams are also supported; see the Quick Tour for the
flow and funnel examples.
---
Integration
Run the MCP server with no install using uvx:
This fetches charted with the MCP extra into a throwaway environment and starts
the server over stdio, so an agent can generate charts without you adding charted
to a project or virtualenv.
Client config
| Client | Setup |
|--------|-------|
| Claude Code | claude mcp add charted -- uvx --from charted[mcp] charted-mcp |
| Cursor, Cline, other clients | Add the JSON below to the client's MCP server config |
The server exposes create_chart, list_chart_types, list_themes, and
chart_from_csv. See the MCP Server section
below for tool details and the pip install path.
Claude Skill
Install the chart Skill in one line:
Chart gallery
The Quick Tour renders every chart type with the code that
produced it. The same examples live in docs/examples/.
---
Why Charted?
- **Zero runtime dependencies**: pure Python, no numpy/pandas required
- **15 chart types**: Bar, Column, Line, Scatter, Pie, Area, Radar, Box Plot, Histogram, Heatmap, Gantt, Bubble, Combo, Polar Area, Sankey
- **Multi-series support**: stacked, side-by-side, grouped layouts
- **Negative values handled**: proper zero baseline calculations
- **SVG and PNG output**: SVG natively, PNG via optional cairosvg (pip install charted[png])
- **Theme system**: 3 built-in presets + custom theme composition
- **Per-series styling**: granular control with SeriesStyle builders
- **Data loading**: CSV/JSON parsers built-in
- **Markdown export**: generate embed-ready markdown snippets
- **CLI included**: create charts without writing Python code
- **Jupyter ready**: charts render inline automatically
- **Base Chart class**: unified API for dynamic chart type selection
---
Quick Tour
Every chart type shares the same simple interface: pass data, labels, dimensions, and a title:
---
---
---
---
---
---
---
---
---
---
Nodes are placed in columns by alignment, then relaxed over several iterations so
connected nodes line up and ribbons cross as little as possible. Link thickness is
proportional to flow value; the widths stacked at each node sum to the node's height.
Pass links as (source, target, value) tuples or {"source", "target", "value"}
dicts; endpoints may be node names or indices. Node labels in a dense column are
nudged apart vertically so they stay readable instead of overlapping.
The alignment option controls how nodes are assigned to columns: justify
(default, like d3-sankey) pushes every sink to the final column; left keeps each
node at its own depth; right aligns by distance from the sink; center is left
with sources pinned to the first column.
**For funnel / drop-off data, use alignment="left".** Funnels have dropout sinks
at many different depths (failed-filter, didn't-respond, cancelled, and so on). Under
the default justify those are all yanked into one tall final column, which crushes
the funnel shape. left lets each dropout terminate at its natural stage, so the
chart reads as a true funnel staircase: