Skip to main content
Glama

smart-charts-mcp

Turn CSV/TSV/TXT/JSON data into standalone interactive ECharts HTML charts — 32 chart types, 3 themes, fully offline (ECharts JS is bundled, zero CDN, works behind corporate firewalls and in air-gapped environments).

Ships as an MCP server so any MCP-capable agent (Claude, Cursor, VS Code, WorkBuddy, ...) can profile a dataset and render charts as a tool call, getting the HTML artifact plus rendering statistics back in the same response.

Why this exists — the traps it removes

Without it you will hit...

This server handles it

Charts that silently use a CDN and render blank offline

ECharts is inlined into every HTML file

Agent guessing chart types and columns from vibes

profile_data returns objective facts (dtype/cardinality/missingness/signals) first; the agent decides from evidence

Captions citing numbers that are not in the chart

render_chart returns plot_stats + data_preview; those are the only numbers a caption may quote

Aggregating by data row instead of by entity (double counting)

source_rows / plotted_rows / unique_entities audit fields on every render

LLM-written pandas snippets doing unsafe things

transform_code runs in a sandbox (AST whitelist + blacklisted builtins, no file/network I/O)

Misleading gauge/liquid "achievement" numbers

achievement is only computed when you pass an explicit business target

Related MCP server: ECharts MCP Server

Tools

  • doctor() — dependency + asset preflight.

  • profile_data(data_text, filename="data.csv") — dataset profile (read-only, nothing rendered).

  • render_chart(data_text, chart_type, title=..., x_axis=..., y_axis=..., transform_code=..., annotation=..., theme=..., target=..., ...) → {ok, html, chart}.

  • list_chart_types() — selection table (best-for + required data shape per type).

data_text is the raw file content as a string; only the extension of filename is used to pick a parser. Binary Excel files are not supported by this transport — export to CSV first.

Install & run

pip install -e .          # mcp + pandas + numpy (+ openpyxl if you need xlsx via local CLI)
python scripts/fetch_assets.py   # one-time ~2.6MB download (ECharts JS + map GeoJSON)
python server.py          # stdio transport

After the one-time fetch the server is fully offline. Distribution zips ship the assets pre-bundled, so zip installs can skip the fetch step. Without the assets, the 29 non-map chart types still work; map, lines, wordcloud and liquid need them.

Or add to your MCP client config:

{
  "mcpServers": {
    "smart-charts": {
      "command": "python",
      "args": ["/path/to/smart-charts-mcp/server.py"]
    }
  }
}

Smoke test

pip install -r requirements-dev.txt
python test_smoke.py      # handshake + tool count + live profile/render round trip

Notes

  • Map charts (map, lines) bundle China province-level and world country GeoJSON offline. For China maps you are responsible for using compliant, officially sanctioned map data in your own jurisdiction.

  • Regression suite: python smart_charts/scripts/regression_check.py.

  • License: MIT.

Available Tools

4 tools
doctorA

Environment preflight: dependency versions and asset readiness. Run once after install.

Inputs: no named parameters.

list_chart_typesA

Chart selection table: each chart type with best-for, trigger keywords and required data shape.

Inputs: no named parameters.

profile_dataA

Profile a tabular dataset BEFORE choosing a chart.

Returns objective facts: per-column dtype/cardinality/missingness/samples/ statistics, entity grain, candidate insight signals (trend, divergent category, head concentration, outliers, strong correlations) and suspected non-data rows. Use these facts to decide which column is an ID, a dimension or a measure, and which chart deserves drawing.

Args: data_text: raw file content (CSV/TSV/TXT/JSON text; xls/xlsx are binary and NOT supported by this tool - use a CSV export instead) filename: original file name, only the extension is used to pick a parser

Inputs: data_text (required), filename.

render_chartA

Render one interactive ECharts HTML chart from tabular data.

Returns {ok, html, chart:{...}} where chart carries the full stdout contract: plot_stats (quote ONLY these numbers in your caption), data_preview (first 10 rendered rows), source_rows/plotted_rows/ unique_entities (aggregation audit), assumptions and advisories (read them before delivering).

Args: data_text: raw file content as text (csv/tsv/txt/json) chart_type: one of line, bar, area, pie, scatter, radar, heatmap, treemap, graph, boxplot, waterfall, gauge, sankey, funnel, sunburst, wordcloud, histogram, stacked_bar, bubble, pareto, combo, venn, mindmap, orgchart, liquid, spreadsheet, map, lines, effect_scatter, calendar, pictorial_bar, theme_river title: conclusion-style title (subject + number), not a noun phrase subtitle: context - time range, filters, source x_axis / y_axis: column name(s); lists become multiple series transform_code: sandboxed pandas code; variables df/pd/np only, must produce a DataFrame named result (no import/open/try/class) annotation: your written interpretation, injected into the HTML footer theme: default | classic | dark label_col: identity column for scatter/bubble/boxplot target: business target for gauge/liquid achievement rate sheet: Excel sheet name (convert to CSV first if using data_text) header_row / skiprows / drop_rows: dirty-header repairs (1-based row)

Inputs: data_text (required), chart_type (required), sheet, theme, +12 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool occupies a clearly distinct slot in the workflow: profile_data analyzes data, list_chart_types is a static reference, render_chart produces output, and doctor checks the environment. There is no plausible case where an agent would mistake one for another.

    Naming Consistency4/5

    Three of four tools follow a clean verb_noun pattern (profile_data, list_chart_types, render_chart), with 'doctor' as the single stylistic deviation. That lone noun-style name is still conventional and unambiguous, so the break is minor.

    Tool Count4/5

    Four tools is lean but well-scoped for a charting server, with each earning its place in a profile-then-render pipeline. The heavy lifting is consolidated into one large render_chart tool, so the surface is slightly thin at the discovery/utility end but not problematic.

    Completeness4/5

    The core lifecycle (preflight, inspect data, choose chart, render HTML) is fully covered, and render_chart itself is extremely broad with 30+ chart types and many options. Minor gaps exist: no tool to persist/export the rendered HTML to a file or to list available datasets, but agents can work around these.

    Related MCP Connectors

    Related MCP Servers