image-charts-mcp

A Model Context Protocol server that turns an agent's chart request into a permanent, hosted Image-Charts image URL.

The URL renders server-side and embeds anywhere an image does — Markdown, HTML <img>, email, Slack, PDF, no-code and low-code tools — with no chart library and no runtime on the client. The agent gets back a string; the picture appears wherever that string is dropped.

Why a URL

Most chart tooling hands an agent raw bytes or an ephemeral in-memory preview that lives and dies inside the session. A hosted URL is different:

• Persistent — the same link keeps rendering long after the conversation ends.

• Portable — paste it into an email, a Notion page, a Slack message, a PDF, a Jira ticket. It just shows up.

• Zero-runtime — the receiving surface needs nothing but the ability to display an image. No JavaScript, no build step, no dependency.

• Deterministic — the chart is fully described by the URL, so it is cacheable and reproducible.

Install

No install step — run it straight from npm:

npx -y image-charts-mcp

Client configuration

Add the server to your MCP client (Claude Desktop, Claude Code, Cursor, or any MCP-capable host):

{
  "mcpServers": {
    "image-charts": {
      "command": "npx",
      "args": ["-y", "image-charts-mcp"],
      "env": {
        "IMAGE_CHARTS_SECRET": "",
        "IMAGE_CHARTS_HOST": ""
      }
    }
  }
}

Both env vars are optional:

Leave them empty for the free, watermarked tier.

Transports

• stdio (default) — what MCP clients use.

• StreamableHTTP (stateless) — npx -y image-charts-mcp --transport http --port 3000, served at http://127.0.0.1:3000/mcp.

Tools

create_chart — describe a chart, get a URL

High-level, Image-Charts-native description. You pick a semantic type and supply data; the server maps it to the correct Image-Charts parameters.

type is one of: bar, bar_grouped, bar_stacked, bar_horizontal, line, area, pie, doughnut, radar, scatter, qr, graph, gauge.

Common fields: title, series ({ name?, data: number[] }, or { name?, points: {x,y}[] } for scatter), labels, colors (hex without #), legend (true / "top" / "bottom" / "left" / "right"), size ({ width, height }), plus qr / graph / gauge option objects, icac, and format (url / png / both).

Bar chart

{
  "type": "bar",
  "title": "Quarterly revenue",
  "series": [
    { "name": "EU", "data": [120, 90, 140] },
    { "name": "US", "data": [80, 130, 100] }
  ],
  "labels": ["Q1", "Q2", "Q3"],
  "colors": ["4285F4", "DB4437"],
  "legend": "bottom"
}

→ https://image-charts.com/chart?cht=bvg&chd=a:120,90,140|80,130,100&chs=700x400&chxt=x,y&chxl=0:|Q1|Q2|Q3&chco=4285F4,DB4437&chdl=EU|US&chdlp=b&chtt=Quarterly+revenue

Pie chart

{
  "type": "pie",
  "title": "Traffic sources",
  "series": [{ "data": [40, 35, 25] }],
  "labels": ["Search", "Direct", "Social"],
  "colors": ["4285F4", "0F9D58", "F4B400"]
}

→ https://image-charts.com/chart?cht=p&chd=a:40,35,25&chs=500x400&chl=Search|Direct|Social&chco=4285F4,0F9D58,F4B400&chtt=Traffic+sources

QR code

{
  "type": "qr",
  "qr": { "data": "https://www.image-charts.com", "errorCorrection": "M", "margin": 4 },
  "size": { "width": 300, "height": 300 }
}

→ https://image-charts.com/chart?cht=qr&chl=https://www.image-charts.com&choe=UTF-8&chld=M|4&chs=300x300

URLs above are shown decoded for readability; the tool returns them percent-encoded.

image_charts_url — raw parameter passthrough

The escape hatch. Pass raw Image-Charts parameters (cht, chd, chs, chco, chxt, chxl, chm, chbh, …) and get the hosted URL, signed automatically when applicable. Use it for anything create_chart does not cover.

{ "cht": "lc", "chd": "a:10,40,25,60", "chs": "600x300", "chco": "4285F4", "chm": "B,4285F433,0,0,0" }

list_chart_types — discovery

Returns every semantic type, the Image-Charts cht it maps to, a description, the inputs it reads, and the concepts Image-Charts cannot render (funnel, treemap, sankey, heatmap, and so on). Call it first if you are unsure which type to use.

Enterprise signing

Image-Charts Enterprise requires each URL to carry an HMAC-SHA256 signature. This server handles it for you:

1. Set IMAGE_CHARTS_SECRET in the server's environment (it stays server-side and is never logged).

2. Pass your account id as icac on create_chart or image_charts_url.

When both are present the returned URL includes &ichm=…:

https://image-charts.com/chart?icac=ic_demo_account&cht=bvg&chd=a:1,2,3&chs=700x400&…&ichm=26d6d5b3…

If the secret is not configured, a bare icac cannot be signed, so it is dropped and you get a valid free-tier URL instead of a broken one. On Dedicated Cloud (IMAGE_CHARTS_HOST) signing is not used at all — the dedicated host handles authorization at the edge.

Development

npm install
npm run build       # tsup → dist/cli.js
npm run typecheck   # tsc --noEmit
npm test            # vitest (black-box, real Image-Charts URL builder, no mocks)

License

MIT