Preview your charts locally

The MCP Inspector shows a tool result as JSON. It cannot render your chart the way a host does. The mcp-charts CLI closes that gap: it renders a ChartSpec or DashboardSpec in the same embedded widget Claude Desktop and ChatGPT use, so your preview equals the production render.

It ships as a bin on the package you already have. There is nothing extra to install:

npx @bonnard/mcp-charts preview ./chart.json

Spec-file mode

Dump a tool's structuredContent to a JSON file, then render it. Add --watch to re-render every time you save.

npx @bonnard/mcp-charts preview ./chart.json --watch

The file can be a single ChartSpec or a full DashboardSpec. The CLI validates it with the same guards the widget uses, so junk or non-spec JSON is rejected with a message that names what it found. The data is baked into the spec, so this mode never touches a database. Reach for it with a captured snapshot or a small hand-made sample, and use MCP mode below when you want live data.

MCP mode

Point the CLI at your running server and let it call a tool, render what the tool returns, and give you a re-run button. This is the loop that renders your real data: the tool runs its query against your connected warehouse, and the CLI renders the fresh result.

npx @bonnard/mcp-charts preview --mcp http://localhost:3000 \
  --tool render_view \
  --args '{"view_id":"sales_overview"}'

--mcp accepts a bare origin, in which case /mcp is appended, or a full endpoint URL if your server mounts it elsewhere. --args is a JSON object of the tool's arguments. The CLI runs the MCP handshake, calls the tool over Streamable HTTP, and pulls the spec out of structuredContent. A tool error or a result that is not a spec surfaces as an actionable message rather than a blank page.

The working loop is: edit your tool code, let your server reload, then click Re-run in the preview. With --watch the CLI re-calls the tool on an interval and repaints only when the spec changes.

Flags

• --watch: re-render on file change (file mode) or re-run the tool on an interval (MCP mode).
• --port <n>: preview server port. Defaults to 4400.
• --theme light|dark: initial widget theme. Defaults to light, and the preview has a toggle.
• --no-open: do not open a browser tab. Useful in a script or over SSH.

What it renders

The preview serves the real embedded widget and feeds it your spec over the same message protocol a host uses. You are looking at the production render, not an approximation, so a chart that reads well here reads the same way in Claude and ChatGPT.

Coming later

Two modes are designed but not yet shipped. A dev command will run the render preview alongside the MCP Inspector, so the protocol view and the chart view sit side by side. A --module mode will import your spec-producing function directly and render its output with no server in the loop.