mcp-chart-forge

A professional chart generation MCP server for Claude Code. Drop a charts-theme.json into any project and Claude can generate beautiful, on-brand charts output as slide-ready PNG and SVG files — fully local, no API keys required.

How it works

1. You add mcp-chart-forge to your Claude Code MCP config (once)
2. You drop a charts-theme.json into your project root (optional — ships with sensible defaults)
3. Claude generates charts via natural language: "Make a bar chart of Q1 revenue by region"
4. PNG + SVG files land in ./charts/ (or wherever your theme configures)

The server uses Vega-Lite for chart specs and sharp for server-side PNG rendering — no browser, no Electron, no API keys.

---

Installation

1. Install dependencies and build

git clone https://github.com/you/mcp-chart-forge.git
cd mcp-chart-forge
npm install
npm run build

2. Add to Claude Code

claude mcp add --transport stdio chart-forge -- node /absolute/path/to/mcp-chart-forge/dist/index.js

Replace /absolute/path/to/mcp-chart-forge with the actual path on your machine.

Or add manually to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chart-forge": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-chart-forge/dist/index.js"]
    }
  }
}

3. Set up your theme (optional)

cp /path/to/mcp-chart-forge/charts-theme.example.json ./charts-theme.json
# Edit charts-theme.json to match your brand colors, fonts, and output size

chart-forge walks up the directory tree from wherever Claude Code is running, so placing charts-theme.json at your project root (or monorepo root) is all you need.

---

Available tools

Tool	Description
generate_bar_chart	Bar chart (vertical or horizontal, optionally grouped/stacked)
generate_line_chart	Line chart with optional multiple series, smoothing
generate_area_chart	Area chart with optional stacking
generate_donut_chart	Donut/ring chart
generate_scatter_chart	Scatter plot with optional bubble size, labels, and trendline

Common parameters (all tools)

Parameter	Type	Description
data	object[]	Array of data objects
xField	string	Field name for X axis
yField	string	Field name for Y axis
title	string	Chart title
subtitle	string?	Optional subtitle
colorField	string?	Field for color grouping
outputName	string?	Filename stem (defaults to slugified-title-{timestamp})
format	"png" | "svg" | "both"	Output format (default: "both")

Tool-specific parameters

generate_bar_chart

• horizontal: boolean — render as horizontal bars (default: false)

generate_line_chart

• xType: "temporal" | "ordinal" | "quantitative" — X axis field type (default: "ordinal")
• smooth: boolean — apply monotone curve smoothing (default: false)

generate_area_chart

• xType: same as line chart
• stacked: boolean — stack series instead of overlapping (default: false)

generate_donut_chart

• innerRadiusRatio: number 0.1–0.9 — hole size as fraction of outer radius (default: 0.55)

generate_scatter_chart

• sizeField: string? — field for bubble size (creates a bubble chart)
• labelField: string? — field for point labels
• showTrendline: boolean — overlay a linear regression line (default: false)

---

Theme file reference

// charts-theme.json
{
  // Brand colors — used as the categorical color range for all charts
  "palette": ["#1B4F8A", "#E8A020", "#4CAF8A", "#C94040", "#7B5EA7"],

  "background": "#FFFFFF",
  "fontFamily": "sans-serif",

  "fontSize": {
    "title":      20,   // Chart title
    "subtitle":   14,   // Chart subtitle
    "axis":       12,   // Axis labels and titles
    "legend":     12,   // Legend labels
    "annotation": 11    // In-chart labels
  },

  "fontWeight": {
    "title":    "bold",
    "subtitle": "normal"
  },

  "textColor":  "#1A1A1A",   // All text
  "axisColor":  "#CCCCCC",   // Axis lines and ticks
  "gridColor":  "#F0F0F0",   // Grid lines

  "padding": { "top": 48, "right": 40, "bottom": 56, "left": 64 },

  "outputSize": {
    "width":  1920,   // Output PNG width in pixels
    "height": 1080,   // Output PNG height in pixels
    "scale":  1       // Use 2 for @2x / HiDPI
  },

  "outputDir": "./charts",   // Relative to project root (process.cwd())

  "logoPath": null            // Reserved for future logo overlay support
}

---

Example prompts for Claude

Generate a bar chart of monthly revenue.
Data: Jan $42k, Feb $38k, Mar $51k, Apr $49k, May $63k

Make a line chart comparing website traffic vs conversions over the last 6 months.
Use "month" for X, "visitors" and "conversions" as separate series via colorField.

Create a donut chart showing market share:
Company A 38%, Company B 27%, Company C 19%, Others 16%

Generate a scatter plot of marketing spend vs revenue, with company name labels,
and show a trendline.

---

Troubleshooting

Could not load the "sharp" module on Windows

Sharp ships prebuilt binaries per-platform. If you see this error, force the Windows x64 binary:

npm install --os=win32 --cpu=x64 sharp

Then rebuild: npm run build.

Could not load the "sharp" module on macOS (Apple Silicon)

npm install --os=darwin --cpu=arm64 sharp

---

Development

npm run dev      # Run via ts-node (no build step)
npm run build    # Compile TypeScript → dist/
npm start        # Run compiled output

Tech stack

• Vega-Lite — declarative chart spec compiler
• Vega — rendering engine (view.toSVG() — no canvas/browser needed)
• sharp — SVG → PNG via libvips (prebuilt binaries, no native compilation)
• @modelcontextprotocol/sdk — MCP server + tool registration
• Zod — tool input validation

License

MIT