# x402-dataviz-mcp

A free MCP (Model Context Protocol) server that renders bar, line, and area
charts from structured data and returns clean, hand-designed SVG. No API
key, no payment, no rate limit games — just an MCP tool any MCP client can
call.

This is the **open funnel twin** of a paid, x402-gated HTTP API:

**[x402-dataviz-poc.theliminalguy.workers.dev](https://x402-dataviz-poc.theliminalguy.workers.dev)**
— `POST /chart`, $0.01 USDC on Base per call via the
[x402 payment protocol](https://x402.org), for production/high-volume or
non-MCP (plain HTTP) use. Same renderer, same output, just billed per call
instead of free-via-MCP.

## Why this exists

The [x402 Bazaar](https://x402.org) (~14,800 agent-payable APIs at time of
writing) has zero coverage in "structured data → clean chart image." This
MCP server is the free/local half of filling that gap — try it for nothing
via MCP; reach for the paid HTTP endpoint when you need it at volume or
outside an MCP client.

## What it does

One tool, `render_chart`, takes a chart type + structured data points and
returns a rendered SVG string. Rendering is hand-rolled (no headless
browser, no native binaries, no heavy charting framework) — just
string-built SVG, so it's fast with zero runtime dependency risk.

The design bar is the actual differentiator: a real categorical color
palette (validated for colorblind-safety, not eyeballed), considered
spacing, thin marks with rounded bar ends, 2px surface gaps between bars,
ringed line markers, direct end-labels, and full light/dark theme support —
not the default-blue/red/green look of a generic charting library.

## Install & run

```bash
npx x402-dataviz-mcp
```

Or add it to an MCP client config (e.g. Claude Desktop's
`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dataviz": {
      "command": "npx",
      "args": ["-y", "x402-dataviz-mcp"]
    }
  }
}
```

## Tool: `render_chart`

Input:

```jsonc
{
  "type": "bar" | "line" | "area",
  "title": "optional string",
  "theme": "light" | "dark",       // defaults to "light"
  "data": [
    { "x": "Q1", "values": { "Revenue": 128000, "Cost": 84000 } },
    { "x": "Q2", "values": { "Revenue": 146500, "Cost": 91200 } }
  ]
}
```

`values` can hold one or more named series; series colors are assigned from
a fixed, colorblind-validated order (never generated/cycled). A legend
renders automatically for 2+ series; a single series needs no legend (the
title already names it).

Output: an SVG string (as MCP tool text content) rendering the requested
chart.

## Local development

```bash
npm install
npm run dev      # runs src/index.ts directly on stdio via tsx
npm run build    # compiles to dist/ for the published npm package
```

## When to use the paid HTTP twin instead

Use [`POST /chart`](https://x402-dataviz-poc.theliminalguy.workers.dev/chart)
on the paid Worker instead of this MCP server when:

- You're calling from outside an MCP client (plain HTTP, any language).
- You need production/high-volume use and want to pay per call rather than
  rely on a free tool being available indefinitely.
- Your agent already speaks x402 (e.g. via `x402-fetch` / `x402-axios`) and
  can pay $0.01 USDC on Base per request.

Both routes call the exact same `renderChart()` function — output is
byte-for-byte identical.

## License

MIT