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:

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

addCharts(server, {
  // your read-only query callback — return { rows } (and optionally typed `fields`)
  runSql: async (sql) => ({ rows: await db.query(sql) }),
  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.

Use a warehouse adapter

Instead of writing runSql by hand, you can use a bundled adapter for your warehouse. Each lives at its own import subpath and turns a native driver result into typed chart data:

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

addCharts(server, { runSql: postgresRunSql(pool) });

See Warehouse Adapters for BigQuery, DuckDB, Postgres, Snowflake, and Databricks.

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.