Getting Started

@bonnard/mcp-charts adds a visualize tool plus an embedded chart widget to any MCP server. Your agent writes SQL, you run it, and the result renders as an interactive chart inside the MCP host (Claude, ChatGPT, and other MCP Apps clients).

Install

npm install @bonnard/mcp-charts

Quickstart

Call addCharts on your existing MCP server and give it a read-only query callback. Use a bundled warehouse adapter so the driver's column types become chart field kinds:

import { addCharts } from "@bonnard/mcp-charts";
import { postgresRunSql } from "@bonnard/mcp-charts/postgres";

addCharts(server, {
  runSql: postgresRunSql(pool), // maps driver column types to chart field kinds
  discovery: { toolName: "explore_schema" }, // your schema-discovery tool
});

That registers a visualize tool and a ui://bonnard/chart widget resource. The agent calls visualize with SQL (and optional presentation hints); the rows render as a chart in the host, with a text fallback for non-widget clients.

Warehouse adapters

Adapters ship for Postgres, BigQuery, DuckDB, Snowflake, and Databricks. Each lives at its own import subpath and turns a native driver result into typed chart data — see Warehouse Adapters.

Writing runSql by hand

Without an adapter, return ChartData yourself. Types matter: the resolver infers field kinds from the row values, so a driver that returns numbers as strings (Postgres NUMERIC/BIGINT, for example) charts a measure as a category unless you pass typed fields.

addCharts(server, {
  runSql: async (sql) => ({ rows: await db.query(sql) }), // only if your driver returns native JS types
});

Security

visualize executes agent-written SQL against your database — treat it as untrusted input. Connect runSql to a read-only, least-privilege role scoped to the data you want exposed. Your database permissions are the only security boundary; the SDK does not sandbox or restrict queries.