MCP server

@microcharts/mcp is a Model Context Protocol server that gives an assistant three tools: find a chart for a question, get its exact props, render it to SVG. It calls the real library, so what comes back is the mark the component draws.

It runs on your machine over stdio. Nothing is hosted, there is no key, and no data leaves the process your client spawns.

Add it to your client

The package ships a microcharts-mcp binary, so every client below spawns the same thing — npx -y @microcharts/mcp. There is no install step of your own: npx fetches it on first run.

Open yours for its command, its config format, and where the file lives.

claude mcp add microcharts -- npx -y @microcharts/mcp

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

codex mcp add microcharts -- npx -y @microcharts/mcp

[mcp_servers.microcharts]
command = "npx"
args = ["-y", "@microcharts/mcp"]

gemini mcp add --scope user microcharts npx -y @microcharts/mcp

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

/mcp add

Name     microcharts
Type     Local (STDIO)
Command  npx -y @microcharts/mcp
Tools    *

{
  "mcpServers": {
    "microcharts": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"],
      "tools": ["*"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "microcharts": {
      "type": "local",
      "command": ["npx", "-y", "@microcharts/mcp"],
      "enabled": true
    }
  }
}

amp mcp add microcharts -- npx -y @microcharts/mcp

{
  "amp.mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

goose configure

> Add Extension
> Command-line Extension

Name     microcharts
Command  npx -y @microcharts/mcp

extensions:
  microcharts:
    type: stdio
    name: microcharts
    enabled: true
    cmd: npx
    args: ["-y", "@microcharts/mcp"]
    envs: {}

{
  "servers": {
    "microcharts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

code --add-mcp '{"name":"microcharts","command":"npx","args":["-y","@microcharts/mcp"]}'

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "context_servers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

Settings | Tools | AI Assistant | Model Context Protocol (MCP)

> + > As JSON > paste the block below > Apply

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"],
      "disabled": false,
      "autoApprove": ["find_microchart", "get_microchart", "render_microchart"]
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "servers": {
    "microcharts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

name: microcharts
version: 0.0.1
schema: v1
mcpServers:
  - name: microcharts
    type: stdio
    command: npx
    args:
      - "-y"
      - "@microcharts/mcp"

Settings > MCP > Add > Add Manually

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

Settings > MCP servers > Add server

Name     microcharts
Transport STDIO
Command  npx -y @microcharts/mcp

[mcp_servers.microcharts]
command = "npx"
args = ["-y", "@microcharts/mcp"]

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

Settings > AI > MCP servers > + Add

> CLI Server (command) > paste the block below > Save

{
  "microcharts": {
    "command": "npx",
    "args": ["-y", "@microcharts/mcp"]
  }
}

A client that isn't listed takes the same two values, whatever it names the fields: the command is npx, and the arguments are -y and @microcharts/mcp. A client that reaches remote connectors only — ChatGPT on the web, a hosted agent builder, a browser-only IDE — cannot spawn a local process at all. Point it at /llms.txt and /catalog.json instead.

Emit, read, call

Three ways a model can end up with a correct chart. They stack; none replaces the others.

Emit is for a surface you control, where you can map a block to a component. Call is for a surface you don't control — a chat reply, a terminal, an email draft — where the model needs the finished mark rather than an instruction to draw one.

The three tools

Call them in order, or one at a time.

find_microchart

Rank the 106 chart types against a question written in plain language.

{ "question": "is the error budget burning down?", "limit": 3 }

[
  {
    "slug": "error-budget",
    "name": "ErrorBudget",
    "tagline": "Are we burning the error budget too fast to survive the window?",
    "dataShape": "number[], budget remaining (0–1) per elapsed step; index 0 = 1.0",
    "why": "an SLO error budget in a KPI card"
  },
  {
    "slug": "burn-chart",
    "name": "BurnChart",
    "tagline": "Will we finish on time?",
    "dataShape": "{ plan: number[]; actual: number[] }, remaining work per period",
    "why": "a sprint burndown in a tab header"
  }
]

why is the bestFor phrase that matched, quoted back rather than generated. An optional dataShape argument filters to the shape you already have.

get_microchart

Everything needed to wire one chart: import paths, its own props plus the shared grammar, best/avoid guidance, a copy-runnable example, and sample — that same example as JSON props.

{ "slug": "bullet" }

{
  "slug": "bullet",
  "staticImport": "@microcharts/react/bullet",
  "interactiveImport": "@microcharts/react/bullet/interactive",
  "dataShape": "value + target + bands",
  "encoding": { "channel": "position (measure length vs a target tick)", "precision": "high" },
  "bestFor": ["progress to goal", "SLA / budget vs target", "KPI with thresholds"],
  "example": { "code": "<Bullet value={72} target={80} bands={[50, 90]} title=\"Quota\" />" },
  "sample": { "value": 72, "target": 80, "bands": [50, 90], "title": "Quota" }
}

The two example forms serve two readers. example.code is JSX, for a human to paste. sample is JSON, for the model to hand straight to render_microchart. Every chart takes its own shape, and guessing between number[], { label, value }[], and { open, high, low, close }[] is where a model goes wrong.

render_microchart

Render to a self-contained SVG plus its generated alt text — for a surface that cannot run React.

{ "type": "sparkline", "data": [132, 148, 141, 165, 159, 182] }

{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"mc-root mc-spark\" …><style>…</style>…</svg>",
  "summary": "Trending up 38%. Range 132 to 182. Last value 182.",
  "mimeType": "image/svg+xml",
  "width": 80,
  "height": 20,
  "library": "0.8.0"
}

Here is that same call as a component on this page, with the same geometry and the same summary:

The default format: "svg" embeds the stylesheet inside the SVG, so the mark renders correctly on a surface with no CSS of its own. Pass format: "bare" when the page already loads @microcharts/react/styles.css.

The tool does not write summary. It reads the chart's own accessible name back out of the rendered markup, the same sentence a screen reader speaks. See Accessibility for how it's generated.

Two resources

Alongside the tools, the server publishes two read-only resources:

• microcharts://catalog — every chart type with its props, data shape, encoding, and the @microcharts/react version the snapshot was cut from.
• microcharts://agent-setup — the same paste-and-run setup prompt served at /agent-setup.md, for when the assistant should wire the library into a repo rather than render a one-off.

What it looks like in practice

import { microchartsTools } from "@microcharts/mcp/ai-sdk";import { streamText } from "ai";const result = streamText({  model,  tools: microchartsTools, // find_microchart · get_microchart · render_microchart  prompt: "Summarise this quarter and show the revenue trend as a chart.",});

How it behaves

A model mid-reply rarely has clean numbers. Every call therefore ends in one of two places: a rendered mark, or a named error. The server never guesses a value to make a call succeed.

Messy data still renders

Degenerate input is a documented case. The chart renders and the summary reports what the data was. These are the real generated sentences:

A gap is never filled with an invented number, and the sentence never claims more than the data supports. These are the same guarantees the components make; Accessibility has the full matrix.

Calls it refuses, and what it says

Refusals come back as tool errors with the fix in the message, so the model can correct itself in one turn instead of retrying blind:

The size limits are deliberate. A series big enough to produce megabytes of markup is a mistake upstream, and returning it would fill the model's context instead of helping.

What comes back

Every render carries role="img" and the generated accessible name, so the mark is usable the moment it lands.

• format: "svg" (default) embeds the stylesheet inside the SVG, so the result stands alone. Because the embedded CSS is the real stylesheet, the mark still answers prefers-color-scheme, forced-colors, and prefers-reduced-motion wherever it lands: a chart pasted into a dark-themed client is drawn for dark.
• format: "bare" drops the embedded CSS for a page that already loads @microcharts/react/styles.css. It is much smaller per response, and the right choice inside your own app.
• mimeType is image/svg+xml for most charts. Delta and TokenConfidence are inline text marks, so they come back as text/html with width/height of 0: they size to the font around them, not to a pixel box.
• library is the @microcharts/react version that drew it.

Props that do cross a tool call

Anything JSON can express: data, value, domain, title, summary, color, categorical colors, label, dots, width, height, className, style, id, and positive. Two are worth calling out:

• locale — "de-DE" gives "Range 1.200 to 1.800.". Number formatting is fully available.
• format — the Intl.NumberFormatOptions half of the union works: { "style": "currency", "currency": "EUR" } yields "Range €1,200.00 to €1,800.00.". The callback half does not (see below).

Passing id switches the chart from aria-label to <title>/<desc> + aria-labelledby, as the component does; summary still comes back correct.

What it can't do

Reach for the component instead when you need any of these:

• It renders the static chart. No hover, keyboard roving, touch scrub, or selection, and animate has no meaning. Those live on the /interactive entry; get_microchart returns interactiveImport so an agent can wire it up in code.
• No annotations. Threshold, TargetZone, Marker, and Callout are React children; JSON has no children.
• No function props. Formatter callbacks and event handlers can't cross a tool call. Use locale and the format options object for numbers, or set summary to supply the sentence yourself.
• No raster output. You get an SVG or HTML string, never a PNG. Anything that renders SVG will show it; anything that won't needs a converter on your side.
• stdio only. Your client spawns the server on your machine. There is no hosted endpoint and no HTTP transport, by design, which is also why nothing you chart leaves the process.
• It doesn't touch your project. No files written, no dependencies installed. To wire the library into a repo, use the agent setup prompt instead.
• Chart props are a closed set. Arbitrary data-* or aria-* attributes are not forwarded. That is a library decision, not a limit of the transport.

Versioning and compatibility

The server carries a snapshot of the catalog and the stylesheet, cut from a specific @microcharts/react release. That version is stamped on the microcharts://catalog resource and returned on every render as library, so a chart you generate can always be traced to the code that drew it.

The two version lines move independently: @microcharts/mcp tracks its own changes, and pulls in a compatible library automatically. Pin the server, not the library, if you need a reproducible render.

Adding a chart

For contributors: nothing about a new chart is written by hand here. The server's catalog is generated from the same chart registry that drives this site, and a test re-derives it from those sources on every run. A chart that lands in the library without the snapshot being regenerated fails CI instead of shipping a server whose catalog is missing it. The rendered sample for every stable chart is exercised in that same suite.

The package lives at @microcharts/mcp, and is listed in the Glama MCP registry. If your assistant doesn't speak MCP, the Quickstart has a paste-and-run prompt that teaches it the library directly, and AI-native covers the grammar it emits.