Graph Visualization MCP App

An interactive data visualization MCP App built with React and Recharts. Create beautiful, interactive charts from raw JSON data or stored datasets. Supports 10 chart types with comprehensive customization options including tooltips, legends, labels, reference elements, brushing, and chart synchronization.

Features

10 Chart Types: Bar, Line, Area, Pie, Composed, Scatter, Radar, Funnel, Sankey, Treemap
Flexible Data Input: Raw JSON arrays or dataset IDs
Smart Chart Detection: Automatically selects optimal chart type based on data structure
Advanced Interactivity:
- Tooltips with custom formatting
- Click-filtering legends
- Data labels with formatters (Percentage, Currency, Decimal, and chart-specific)
- Reference lines and areas
- Range selection with brush tool
- Multi-chart synchronization
Layout Options: Horizontal/vertical layouts, stacking modes including population pyramids
Dual Y-Axes: For composed charts with different scales
Responsive Design: Adapts to any container size
Theme Support: Light and dark themes with CSS variable integration
Data Flexibility: Works with any JSON structure - automatically detects numeric columns

Installation

npm install

Building

npm run build

This builds the React UI into a single HTML file that can be embedded in MCP hosts.

Running the Server

npm run serve

Or in development mode:

npm run dev

The server listens on stdio and communicates with MCP hosts (like Claude Desktop).

API Reference

Tool: `create_visualization`

Creates an interactive chart from your data.

Required Parameters

Parameter	Type	Description
`data`	array \| object	Raw JSON data array OR `{ datasetId: string }` for stored datasets

Chart Configuration

Parameter	Type	Description
`chartType`	string	Chart type: `bar`, `line`, `area`, `pie`, `composed`, `scatter`, `radar`, `funnel`, `sankey`, `treemap`. If omitted, auto-detected from data.
`title`	string	Chart title
`subtitle`	string	Optional subtitle
`theme`	string	`light` or `dark` (default: `light`)
`responsive`	boolean	Auto-resize to container (default: true)

Axis Configuration

Parameter	Type	Description
`xAxis`	string	Column name for X-axis (defaults to first column)
`yAxis`	string \| string[]	Column name(s) for left Y-axis (defaults to first numeric column)
`yAxis2`	string \| string[]	Column name(s) for right Y-axis (composed charts only)
`layout`	string	`horizontal` or `vertical` for bar/area charts
`axisConfig`	object	Advanced axis configuration (see Axis Configuration section)

Series and Data Configuration

Parameter	Type	Description
`series`	string[]	Column names to visualize (auto-detected if omitted)
`seriesConfig`	object	For composed charts: map series to type (`bar`, `line`, `area`)

Bar Chart Options

Parameter	Type	Description
`barSize`	number \| string	Width/height of bars
`barGap`	number \| string	Gap between bar groups (e.g., `"20%"`)
`barCategoryGap`	number \| string	Gap between categories
`barRadius`	number \| number[]	Corner radius (number or `[topLeft, topRight, bottomRight, bottomLeft]`)
`maxBarSize`	number	Maximum bar size
`stackOffset`	string	Stacking mode: `none`, `expand`, `positive`, `sign`, `silhouette`, `wiggle`. Use `sign` for population pyramids.
`reverseStackOrder`	boolean	Reverse stacking order
`baseValue`	number \| string	Base value for stacking (`dataMax`, `dataMin`, or number)

Line and Area Options

Parameter	Type	Description
`curveType`	string	Curve type: `monotone`, `natural`, `linear`, `cardinal`, `catmullRom`
`strokeWidth`	number	Line width
`fillOpacity`	number	Fill transparency (0-1)
`dotSize`	number	Data point marker size
`dotColor`	string	Data point color

Animation

Parameter	Type	Description
`animationDuration`	number	Animation duration in milliseconds (default: 800)
`animationEasing`	string	Easing function: `ease`, `linear`, `easeIn`, `easeOut`, `easeInOut`

Labels

Parameter	Type	Description
`label`	object	Label configuration (see Label Configuration section)

Components

Parameter	Type	Description
`tooltip`	object	Tooltip configuration (see Tooltip Configuration section)
`legend`	object	Legend configuration (see Legend Configuration section)
`brush`	object	Range selection brush (see Brush Configuration section)
`referenceElements`	array	Reference lines and areas (see Reference Elements section)

Styling

Parameter	Type	Description
`palette`	string[]	Custom color palette (array of hex colors)
`styling`	object	Margins, padding, background, border styling
`width`	number \| string	Chart width
`height`	number \| string	Chart height

Interactivity

Parameter	Type	Description
`syncId`	string	Synchronize multiple charts with same ID
`syncMethod`	string	Sync by: `index` or `value`
`clickable`	boolean	Enable click interactions

Pie/Radar Specific

Parameter	Type	Description
`cx`	number \| string	Center X position (default: `50%`)
`cy`	number \| string	Center Y position (default: `50%`)
`innerRadius`	number	Inner radius for donut charts
`outerRadius`	number	Outer radius
`startAngle`	number	Start angle in degrees (default: 0)
`endAngle`	number	End angle in degrees (default: 360)

Scatter Specific

Parameter	Type	Description
`bubbleSize`	number \| string	Size mapping (use `auto` or number)
`bubbleColor`	string	Bubble color

Configuration Details

Label Configuration

Controls how data labels appear on chart elements:

{
  "label": {
    "enabled": true,
    "position": "top",
    "formatter": "Percentage",
    "offset": 5,
    "angle": 0,
    "color": "#333",
    "fontSize": 12
  }
}

Formatter Options:

Standard Formatters: Percentage, Currency, Decimal, default
Chart-Specific Formatters: percentage, value, name, conversion

Tooltip Configuration

Customize hover/click tooltips:

{
  "tooltip": {
    "enabled": true,
    "trigger": "hover",
    "shared": true,
    "position": "auto",
    "contentStyle": { "backgroundColor": "#fff", "border": "1px solid #ccc" },
    "wrapperStyle": { "outline": "none" }
  }
}

Legend Configuration

Control legend appearance and behavior:

{
  "legend": {
    "enabled": true,
    "layout": "horizontal",
    "align": "center",
    "verticalAlign": "bottom",
    "iconType": "square",
    "onClick": "filter"
  }
}

onClick values: filter (hide series), highlight, none

Brush Configuration

Add range selection tool to charts:

{
  "brush": {
    "enabled": true,
    "dataStartIndex": 0,
    "dataEndIndex": 10,
    "height": 40,
    "fill": "rgba(0,0,0,0.1)",
    "stroke": "#999"
  }
}

Reference Elements

Add reference lines and areas:

{
  "referenceElements": [
    {
      "type": "line",
      "value": 5000,
      "stroke": "#ff0000",
      "strokeDasharray": "5 5",
      "label": "Target"
    },
    {
      "type": "area",
      "value": [3000, 7000],
      "fill": "#00ff00",
      "fillOpacity": 0.1
    }
  ]
}

Axis Configuration

Advanced axis customization:

{
  "axisConfig": {
    "x": {
      "type": "category",
      "label": "Time",
      "labelAngle": 45,
      "hide": false,
      "scale": "linear",
      "tickCount": 5
    },
    "y": {
      "type": "number",
      "label": "Value",
      "scale": "linear",
      "domain": [0, 10000]
    },
    "y2": {
      "type": "number",
      "label": "Other",
      "scale": "logarithmic"
    }
  }
}

Styling Configuration

{
  "styling": {
    "margin": { "top": 20, "right": 20, "bottom": 20, "left": 60 },
    "padding": 10,
    "backgroundColor": "#ffffff",
    "borderRadius": 4,
    "borderColor": "#e0e0e0",
    "borderWidth": 1
  }
}

Examples

Bar Chart - Monthly Sales:

{
  "data": [
    { "month": "Jan", "sales": 4000, "revenue": 2400 },
    { "month": "Feb", "sales": 3000, "revenue": 1398 },
    { "month": "Mar", "sales": 2000, "revenue": 9800 }
  ],
  "chartType": "bar",
  "title": "Monthly Sales",
  "xAxis": "month",
  "series": ["sales", "revenue"],
  "theme": "light"
}

Composed Chart - Sales with Profit Margin:

{
  "data": [
    { "month": "Jan", "sales": 4000, "margin": 24 },
    { "month": "Feb", "sales": 3000, "margin": 22 },
    { "month": "Mar", "sales": 2000, "margin": 32 }
  ],
  "chartType": "composed",
  "title": "Sales and Profit Margin",
  "seriesConfig": { "sales": "bar", "margin": "line" },
  "label": { "enabled": true }
}

Scatter Plot - 2D Analysis:

{
  "data": [
    { "temperature": 20, "humidity": 40, "location": "A" },
    { "temperature": 25, "humidity": 55, "location": "B" }
  ],
  "chartType": "scatter",
  "title": "Temperature vs Humidity",
  "xAxis": "temperature",
  "series": ["humidity"],
  "bubbleSize": "auto"
}

Stacked Bar - Population Pyramid:

{
  "data": [
    { "ageGroup": "0-10", "male": -50, "female": 48 },
    { "ageGroup": "10-20", "male": -60, "female": 58 }
  ],
  "chartType": "bar",
  "title": "Population Pyramid",
  "layout": "horizontal",
  "stackOffset": "sign",
  "barGap": "-100%",
  "series": ["male", "female"]
}

Radar Chart - Multi-Metric Comparison:

{
  "data": [
    { "metric": "Speed", "product_a": 85, "product_b": 70 },
    { "metric": "Reliability", "product_a": 78, "product_b": 90 }
  ],
  "chartType": "radar",
  "title": "Product Comparison",
  "theme": "dark"
}

Pie Chart - Market Share:

{
  "data": [
    { "company": "A", "share": 30 },
    { "company": "B", "share": 25 },
    { "company": "C", "share": 45 }
  ],
  "chartType": "pie",
  "title": "Market Share",
  "label": { "enabled": true, "formatter": "percentage" }
}

Sankey Diagram - Data Flow:

{
  "data": [
    { "source": "A", "target": "B", "value": 100 },
    { "source": "B", "target": "C", "value": 80 }
  ],
  "chartType": "sankey",
  "title": "Data Flow"
}

Treemap - Hierarchical Data:

{
  "data": [
    { "name": "A", "value": 100 },
    { "name": "B", "value": 200 }
  ],
  "chartType": "treemap",
  "title": "Hierarchy"
}

Synchronized Charts:

{
  "data": [...],
  "syncId": "chart-group-1",
  "syncMethod": "index"
}

Chart Type Auto-Detection

When chartType is not specified, the app intelligently analyzes data structure and detects the best visualization:

Condition	Auto-Selected Type	Example Data
Data with `source`, `target`, `value` columns	Sankey	Flow diagrams, migration patterns
Data with `children` and `name` properties OR `name`/`value` pairs	Treemap	Hierarchical data, disk usage
Exactly 2 numeric series	Scatter	X-Y coordinate data
3+ numeric series	Radar	Multi-metric comparison
Single series, 2-15 items with generally decreasing values	Funnel	Conversion funnels
Single series, 3-20 categories	Pie	Proportional data
2+ series	Composed	Mixed chart types (bar + line)
Single series (default)	Bar	Categorical data

Supported Datasets

The mock database currently includes:

sales-2024: Monthly sales, revenue, and profit data (Jan-Jun with values up to 9800)

Project Structure

src/
├── app.tsx                 # React app entry point with MCP App lifecycle
├── types.ts               # TypeScript type definitions (ChartConfig, ParsedChartConfig)
├── components/
│   ├── ChartRenderer.tsx   # Main chart routing component
│   └── charts/
│       ├── BarChart.tsx         # Bar charts (horizontal & vertical layouts)
│       ├── LineChart.tsx        # Line and spline charts
│       ├── AreaChart.tsx        # Area and stacked area charts
│       ├── PieChart.tsx         # Pie and donut charts
│       ├── ComposedChart.tsx    # Mixed bar/line/area charts with dual Y-axes
│       ├── ScatterChart.tsx     # Scatter and bubble charts with category support
│       ├── RadarChart.tsx       # Radar charts with auto-transposition
│       ├── FunnelChart.tsx      # Funnel and conversion charts
│       ├── SankeyChart.tsx      # Sankey/flow diagrams
│       ├── TreemapChart.tsx     # Treemap hierarchical charts
│       └── CustomTooltip.tsx    # Shared tooltip component
├── utils/
│   ├── parseConfig.ts       # Configuration parsing, chart type inference, data validation
│   ├── chartColors.ts       # Theme color palettes (light & dark)
│   ├── labelConfig.ts       # Label formatter implementations
│   ├── tooltipConfig.ts     # Tooltip configuration helpers
│   └── legendConfig.ts      # Legend configuration and click handlers
├── index.html              # HTML template
server.ts                   # MCP server with tool & resource registration
vite.config.ts             # Vite build configuration with single-file bundling
package.json               # Dependencies and build scripts

Advanced Features

Label Formatters

The app supports multiple label formatting options to display data in different ways:

Standard Formatters (all chart types):

Percentage: Shows value as percentage of total
Currency: Formats as currency
Decimal: Shows numeric value
default: Shows raw value

Chart-Specific Formatters:

percentage: Chart-specific percentage formatting
value: Raw numeric value
name: Series/category name
conversion: Conversion rate formatting

Stacking Modes

For bar and area charts, choose how overlapping series stack:

none: Side-by-side bars
expand: Stack to 100%
positive: Stack positive values upward
sign: Stack positive up, negative down (for population pyramids)
silhouette: Center stacked area
wiggle: Minimize wiggle in stacked area

Population Pyramids

Create age/gender pyramids with:

{
  "chartType": "bar",
  "layout": "horizontal",
  "stackOffset": "sign",
  "barGap": "-100%",
  "series": ["male", "female"]
}

With negative values for the left side and positive for the right.

Dual Y-Axes

Combine charts with different scales using composed chart type:

{
  "chartType": "composed",
  "series": ["sales", "margin"],
  "seriesConfig": { "sales": "bar", "margin": "line" },
  "yAxis": "sales",
  "yAxis2": "margin"
}

Legend Click Filtering

Click legend items to show/hide series (set legend.onClick to "filter").

Range Selection Brush

Add an interactive range selector with brush configuration to zoom into data ranges.

Multi-Chart Synchronization

Synchronize tooltips and selection across multiple charts using syncId:

{
  "syncId": "dashboard-1",
  "syncMethod": "index"
}

Radar Chart Data Transposition

Radar charts automatically detect and handle two data patterns:

Standard: Data items are angle points, series are polygons
Transposed: Series are angle points, data items are polygons

The app automatically transposes when series count exceeds data item count.

Categorical Scatter Plots

Scatter plots automatically detect categorical data and render with proper legends and distinct colors per category.

Theme Customization

Themes are preset and automatically matched to the host's theme when available:

Light Theme: Bright backgrounds (#fff) with dark text (#333)
Dark Theme: Dark backgrounds (#1e1e1e) with light text (#e0e0e0)

Both use carefully selected color palettes optimized for readability and accessibility.

Development

Technologies

React 19: Modern UI framework with hooks and automatic batching
Recharts: Composable chart library built on D3 with responsive containers
MCP Apps SDK: Model Context Protocol extension for interactive UIs
TypeScript: Strict type safety for configuration and components
Zod: Schema validation for tool inputs
Vite: Fast build tool with HMR support
Node.js: JavaScript runtime environment

Prerequisites

Node.js 16+ (installation: https://nodejs.org/)

Local Development

Install dependencies:

npm install

Start development server with hot reload:

npm run dev

Build for production:

npm run build

Run the MCP server (production):

npm run serve

Build Output

The build process generates:

dist/src/index.html - Single-file bundled HTML with all JS, CSS, and dependencies embedded
Ready for deployment to any MCP-compatible host

Architecture Notes

Server Side (server.ts):
- Registers create_visualization MCP tool with Zod schema validation
- Registers UI resource endpoint serving bundled HTML
- Tool receives configuration and echoes it back to UI
Client Side (src/app.tsx):
- MCP App lifecycle handlers receive tool input and results
- Parses configuration with parseConfig() utility
- Routes to appropriate chart component based on type
- Handles responsive sizing and theme integration
Chart Components:
- Each chart type is a separate React component
- Shared utilities for colors, labels, tooltips, legends
- Responsive containers adapt to parent size
- Click handlers for legend filtering
Data Flow:
- User calls tool → Server validates with Zod → Returns config as text
- UI receives and parses config → Detects chart type → Renders chart
- User interacts with chart (legend click, tooltip hover, etc.)

Testing

Setup

First, build the app:

npm run build

This generates the compiled server at dist/main.js and bundled UI at dist/src/index.html.

With Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "graph_visualization": {
      "command": "node",
      "args": ["/path/to/graph_visualization_mcp_app/dist/main.js"],
      "cwd": "/path/to/graph_visualization_mcp_app"
    }
  }
}

Replace /path/to/graph_visualization_mcp_app with the actual path to your repository.

Then restart Claude Desktop and use the create_visualization tool.

With Claude Code (VS Code)

Edit the settings in Claude Code VS Code extension configuration:

{
  "mcpServers": {
    "graph_visualization": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/graph_visualization_mcp_app/dist/main.js"],
      "cwd": "/path/to/graph_visualization_mcp_app"
    }
  }
}

Note: Use the full path to the node binary on your system:

macOS (Homebrew): /opt/homebrew/bin/node
macOS (NVM): ~/.nvm/versions/node/v<version>/bin/node
Linux: /usr/bin/node or wherever Node is installed
Windows: C:\Program Files\nodejs\node.exe

Then restart VS Code and the tool will be available in Claude Code.

With HTTP Transport

For testing during development, modify server.ts to use HTTP instead of stdio:

const server = createServer();
// Export HTTP handler for testing
export default {
  fetch: async (req: Request) => {
    // Handle JSON-RPC requests here
    return new Response(JSON.stringify({ error: "Not implemented" }));
  }
};

Performance Notes

Data sets up to ~10,000 items render smoothly
Recharts handles responsive resizing efficiently
Labels disabled by default for large datasets (enable with label.enabled)
Brush component recommended for datasets > 1,000 items for interactive filtering

Notes

Data Format: Flexible - any JSON array of objects works. Numeric columns auto-detected.
Missing Data: Non-numeric values are skipped; series auto-detected from numeric columns.
Axis Labels: For category axes, data is assumed to have repeating values. For numeric axes, continuous ranges are used.
Theme Integration: Automatically uses host's theme CSS variables when available (Claude Desktop).
Accessibility: Charts include proper ARIA labels and keyboard navigation support in Recharts.
Export: Charts can be screenshotted but don't have built-in export functionality.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
.gitignore		.gitignore
ACCESSIBILITY_GUIDE.md		ACCESSIBILITY_GUIDE.md
BRUSH_USAGE_GUIDE.md		BRUSH_USAGE_GUIDE.md
CLAUDE.md		CLAUDE.md
DOCUMENTATION_INDEX.md		DOCUMENTATION_INDEX.md
FEATURES.md		FEATURES.md
INTEGRATION_GUIDE.md		INTEGRATION_GUIDE.md
INTEGRATION_REPORT.md		INTEGRATION_REPORT.md
README.md		README.md
REFERENCE_CONFIG_GUIDE.md		REFERENCE_CONFIG_GUIDE.md
SYNC_IMPLEMENTATION_GUIDE.md		SYNC_IMPLEMENTATION_GUIDE.md
TASK_16_COMPLETION_SUMMARY.md		TASK_16_COMPLETION_SUMMARY.md
index.ts		index.ts
main.ts		main.ts
package-lock.json		package-lock.json
package.json		package.json
server.ts		server.ts
tsconfig.json		tsconfig.json
tsconfig.server.json		tsconfig.server.json
vite.config.ts		vite.config.ts

OSS-GR/graph_visualization_mcp_app

Folders and files

Latest commit

History

Repository files navigation

Graph Visualization MCP App

Features

Installation

Building

Running the Server

API Reference

Tool: create_visualization

Required Parameters

Chart Configuration

Axis Configuration

Series and Data Configuration

Bar Chart Options

Line and Area Options

Animation

Labels

Components

Styling

Interactivity

Pie/Radar Specific

Scatter Specific

Configuration Details

Label Configuration

Tooltip Configuration

Legend Configuration

Brush Configuration

Reference Elements

Axis Configuration

Styling Configuration

Examples

Chart Type Auto-Detection

Supported Datasets

Project Structure

Advanced Features

Label Formatters

Stacking Modes

Population Pyramids

Dual Y-Axes

Legend Click Filtering

Range Selection Brush

Multi-Chart Synchronization

Radar Chart Data Transposition

Categorical Scatter Plots

Theme Customization

Development

Technologies

Prerequisites

Local Development

Build Output

Architecture Notes

Testing

Setup

With Claude Desktop

With Claude Code (VS Code)

With HTTP Transport

Performance Notes

Notes

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Tool: `create_visualization`

Packages