Lets an AI client select, validate, repair, and render React data visualizations including charts, network graphs, and geographic maps.
Also known as nteract/semiotic
- Stars
- 2,717
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 3.13.3
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is Semiotic MCP?
Semiotic lets an AI client select, validate, repair, and render React data visualizations including charts, network graphs, and geographic maps. It exposes 5 tools, such as createChart, improveChart, explainChart.
Summary generated from the project's README
About Semiotic MCP server
Developers building React applications can use Semiotic to implement a wide variety of data visualizations, ranging from standard XY charts to complex network graphs and geographic maps. The library is specifically designed to support AI-assisted development by providing structured schemas, diagnostics, and rendering evidence that allow coding assistants to implement, check, and repair chart configurations effectively.
Users can integrate components like LineChart, BarChart, and Scatterplot for basic data representation, or utilize specialized modules for advanced needs. This includes real-time streaming metrics with decay features, force-directed graphs for network analysis, and choropleth maps for geographic data. The system also supports coordinated views through LinkedCharts, where hovering over one visualization highlights related data in another. For those transitioning from other formats, the library includes tools to translate Vega-Lite specifications into Semiotic components.
What you can do with it
- 1Repair broken chart configurationsAn AI assistant can use diagnostics and rendering evidence to fix incorrect chart properties.
- 2Create real-time monitoring dashboardsDevelopers can build live charts that handle streaming data and flag stale information.
- 3Convert Vega-Lite specs to ReactYou can transform existing Vega-Lite specifications into functional Semiotic JSX components.
- 4Build interactive coordinated dashboardsCreate multiple charts that react to user interaction by highlighting shared data selections.
Written from the project's README. Every use case is checked against a quote from it.
How to install Semiotic MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Semiotic MCP in Claude Code
$ claude mcp add semiotic -- npx -y semioticInstall Semiotic MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"semiotic": {
"command": "npx",
"args": [
"-y",
"semiotic"
]
}
}
}Install Semiotic MCP in VS Code
.vscode/mcp.json
{
"servers": {
"semiotic": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"semiotic"
]
}
}
}Install Semiotic MCP in VS Code CLI
$ code --add-mcp '{"name":"semiotic","type":"stdio","command":"npx","args":["-y","semiotic"]}'Install Semiotic MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"semiotic": {
"command": "npx",
"args": [
"-y",
"semiotic"
]
}
}
}Install Semiotic MCP in Codex
$ codex mcp add semiotic -- npx -y semioticInstall Semiotic MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.semiotic] command = "npx" args = ["-y", "semiotic"]
Install Semiotic MCP in Gemini CLI
$ gemini mcp add -s user semiotic npx -- -y semioticInstall Semiotic MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"semiotic": {
"command": "npx",
"args": [
"-y",
"semiotic"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for semiotic 3.13.3 in an isolated container with no network and no keys. It answered and listed 24 tools.
Semiotic MCP tools 5
Read from the server with tools/listcreateChartRead-onlySelect, validate, diagnose, render, and prove a static-data Semiotic chart. This is the default public workflow.
improveChartRead-onlyDiagnose a chart configuration, assess data fit, and propose repairs or variants.
explainChartRead-onlyReturn reader grounding: chart description, communicative intent, and navigable data structure.
auditChartRead-onlyRun design diagnostics plus accessibility and mobile audits, returning prioritized structured findings.
getChartSchemaRead-onlyReturn canonical Semiotic prop-schema guidance for code editing and advanced configuration.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablenteract/semiotic is public and reachablegithub.com/nteract/semiotic ↗Pass
- Package names this repository as its sourcesemiotic names nteract/semiotic as sourcenpmjs.com/package/semiotic ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for semioticnpmjs.com/package/semiotic/v/3.13.3#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/nteract/semiotic ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 5.4 / 10; weakest: Token-Permissions 0, CII-Best-Practices 0, Signed-Releases 0scorecard.dev/viewer/?uri=github.com/nteract/semiotic ↗Partial 8/15
- Package name not close to a popular packageNo popular package one edit away from semioticPass
- No critical advisory in the package or its dependencies95 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 200 ms; tools/list returned 5 toolsPass
README
View on GitHubA React data visualization library designed for AI-assisted development and streaming data.
Install
npm install semiotic
Requires React 18.1+ or React 19.
First Chart
import { LineChart } from "semiotic/xy"
const signups = [
{ week: 1, signups: 120 },
{ week: 2, signups: 180 },
{ week: 3, signups: 150 },
{ week: 4, signups: 240 },
{ week: 5, signups: 310 },
]
export default function SignupsChart() {
return (
<LineChart
data={signups}
xAccessor="week"
yAccessor="signups"
xLabel="Week"
yLabel="Signups"
title="Weekly signups"
/>
)
}
xAccessor and yAccessor name the fields to plot, and title gives the
chart its accessible name. LineChart needs numeric x values (numbers or
timestamps); for named categories such as month names, use BarChart with
categoryAccessor. More complete examples follow under
Quick Examples.
Start with a small chart component. Add network graphs, streaming data and coordinated views when the task needs them. Structured schemas, diagnostics and rendering evidence help coding assistants implement, check and repair chart configurations.
Work through a complete task: check category totals, maintain a live chart, or correct a published chart. The source task packets identify their build and evidence scope; source availability does not establish installed or deployed parity.
Quick Examples
Each example is a complete component. Examples that use one chart family
import from that family's entry; the coordination examples import from
semiotic, which exports LinkedCharts and ChartContainer alongside the
charts.
Standard Charts
Line, bar, scatter, and area charts share the same accessor-driven API:
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
const revenue = [
{ month: 1, revenue: 4200 },
{ month: 2, revenue: 5100 },
{ month: 3, revenue: 6800 },
{ month: 4, revenue: 5900 },
]
const departments = [
{ department: "Design", region: "East", sales: 12 },
{ department: "Sales", region: "West", sales: 30 },
{ department: "Support", region: "East", sales: 18 },
]
export function StandardCharts() {
return (
<>
<LineChart
data={revenue}
xAccessor="month" yAccessor="revenue"
curve="monotoneX" showPoints
title="Monthly revenue"
/>
<BarChart
data={departments}
categoryAccessor="department" valueAccessor="sales"
orientation="horizontal" colorBy="region"
title="Sales by department"
/>
</>
)
}
Coordinated Dashboard
Hover one chart and highlight the same data in another through a shared selection:
import { LinkedCharts, Scatterplot, BarChart } from "semiotic"
const people = [
{ age: 31, income: 52, region: "East" },
{ age: 44, income: 78, region: "West" },
{ age: 38, income: 61, region: "East" },
{ age: 52, income: 90, region: "West" },
]
const totals = [
{ region: "East", total: 113 },
{ region: "West", total: 168 },
]
export function RegionDashboard() {
return (
<LinkedCharts>
<Scatterplot
data={people} xAccessor="age" yAccessor="income" colorBy="region"
linkedHover={{ name: "hl", fields: ["region"] }}
selection={{ name: "hl" }}
title="Income by age"
/>
<BarChart
data={totals} categoryAccessor="region" valueAccessor="total"
selection={{ name: "hl" }}
title="Total income by region"
/>
</LinkedCharts>
)
}
Streaming Metrics with Decay
Live data fades old points, flashes new ones, flags stale feeds. Omit data
and push through a ref from an effect, an event handler, or a socket callback:
import { useEffect, useRef } from "react"
import { RealtimeLineChart } from "semiotic/realtime"
export function CpuMonitor() {
const chartRef = useRef(null)
useEffect(() => {
// Replace the timer with your metrics source.
const timer = setInterval(() => {
chartRef.current?.push({ time: Date.now(), value: 40 + Math.random() * 20 })
}, 250)
return () => clearInterval(timer)
}, [])
return (
<RealtimeLineChart
ref={chartRef}
timeAccessor="time"
valueAccessor="value"
decay={{ type: "exponential", halfLife: 100 }}
staleness={{ threshold: 5000, showBadge: true }}
title="CPU load"
/>
)
}
Network Graphs
Force-directed graphs and Sankey diagrams — same API as LineChart:
import { ForceDirectedGraph, SankeyDiagram } from "semiotic/network"
const people = [
{ id: "Ada", team: "Platform" },
{ id: "Lin", team: "Design" },
{ id: "Sam", team: "Platform" },
]
const friendships = [
{ source: "Ada", target: "Lin" },
{ source: "Lin", target: "Sam" },
]
const budgetFlows = [
{ from: "Budget", to: "Design", amount: 40 },
{ from: "Budget", to: "Engineering", amount: 60 },
{ from: "Engineering", to: "Platform", amount: 35 },
]
export function Networks() {
return (
<>
<ForceDirectedGraph
nodes={people} edges={friendships}
colorBy="team" nodeSize={8} showLabels
title="Who works with whom"
/>
<SankeyDiagram
edges={budgetFlows}
sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
title="Where the budget goes"
/>
</>
)
}
Geographic Visualization
Choropleth maps, flow maps, and distance cartograms with canvas rendering,
zoom/pan, tile basemaps, and animated particles. This example joins your rows
to the bundled world-110m geography, which needs the optional world-atlas
peer dependency (npm install world-atlas):
import { useEffect, useState } from "react"
import { ChoroplethMap, mergeData, resolveReferenceGeography } from "semiotic/geo"
const gdpByCountry = [
{ country: "United States of America", gdp: 27.4 },
{ country: "China", gdp: 17.8 },
{ country: "Germany", gdp: 4.5 },
]
export function WorldGdpMap() {
const [areas, setAreas] = useState([])
useEffect(() => {
let cancelled = false
resolveReferenceGeography("world-110m").then((world) => {
if (cancelled) return
setAreas(
mergeData(world, gdpByCountry, { featureKey: "properties.name", dataKey: "country" })
)
})
return () => {
cancelled = true
}
}, [])
return (
<ChoroplethMap
areas={areas}
valueAccessor={(feature) => feature.properties.gdp}
colorScheme="viridis" projection="equalEarth" zoomable tooltip
title="GDP by country"
/>
)
}
FlowMap and DistanceCartogram follow the same accessor pattern. In this
sketch airports, routes, and cities stand for your own arrays:
import { FlowMap, DistanceCartogram } from "semiotic/geo"
<FlowMap
nodes={airports} flows={routes} valueAccessor="passengers"
showParticles particleStyle={{ color: "source", speedMultiplier: 1.5 }}
/>
<DistanceCartogram
points={cities} center="rome" costAccessor="travelDays"
showRings costLabel="days" lines={routes}
/>
Streaming System Monitor
Live service topology with threshold alerting and click-to-inspect:
import { useEffect, useRef } from "react"
import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"
export function SystemMonitor() {
const chartRef = useRef(null)
useEffect(() => {
// Replace the timer with your request stream.
const timer = setInterval(() => {
chartRef.current?.push({ source: "API", target: "Orders", value: 15 })
}, 500)
return () => clearInterval(timer)
}, [])
return (
<LinkedCharts>
<ChartContainer title="System Monitor" status="live"
detailsPanel={
<DetailsPanel position="right" trigger="click">
{(datum) => <div>{datum.id}: {datum.value} req/s</div>}
</DetailsPanel>
}>
<StreamNetworkFrame ref={chartRef} chartType="sankey"
showParticles particleStyle={{ proportionalSpeed: true }}
thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
/>
</ChartContainer>
</LinkedCharts>
)
}
All Chart Components
| Category | Components |
|---|---|
| XY | LineChart AreaChart DifferenceChart StackedAreaChart BumpChart Scatterplot ConnectedScatterplot BubbleChart Heatmap QuadrantChart MultiAxisLineChart MinimapChart CandlestickChart WaterfallChart ScatterplotMatrix |
| Categorical | BarChart StackedBarChart GroupedBarChart LikertChart SwimlaneChart FunnelChart SwarmPlot BoxPlot Histogram ViolinPlot RidgelinePlot DotPlot PieChart DonutChart GaugeChart RadarChart |
| Network | ForceDirectedGraph ChordDiagram SankeyDiagram ProcessSankey TreeDiagram Treemap CirclePack OrbitDiagram |
Geo (semiotic/geo) |
ChoroplethMap ProportionalSymbolMap FlowMap DistanceCartogram |
| Realtime | RealtimeLineChart RealtimeHistogram TemporalHistogram RealtimeSwarmChart RealtimeWaterfallChart RealtimeHeatmap |
Physics (semiotic/physics) |
GaltonBoardChart EventDropChart UnitPileChart CollisionSwarmChart GauntletChart CrucibleChart ProcessFlowChart PacketFlowChart ChainReactionChart |
| Value and text | BigNumber (semiotic/value) WordCloud (semiotic/wordcloud) |
| Custom layouts | XYCustomChart OrdinalCustomChart NetworkCustomChart GeoCustomChart (semiotic/geo) PhysicsCustomChart (semiotic/physics) |
| Coordination | LinkedCharts |
| Layout | ChartGrid ContextLayout CategoryColorProvider |
| Frames | StreamXYFrame StreamOrdinalFrame StreamNetworkFrame StreamGeoFrame (semiotic/geo) StreamPhysicsFrame (semiotic/physics) |
Vega-Lite Translation
Paste a Vega-Lite spec, get a Semiotic chart:
import { fromVegaLite } from "semiotic/data"
import { configToJSX, fromConfig } from "semiotic"
const config = fromVegaLite({
mark: "bar",
data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
encoding: {
x: { field: "a", type: "nominal" },
y: { field: "b", type: "quantitative" },
},
})
// Render directly
const { componentName, props } = fromConfig(config)
// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }
// Or generate JSX code
configToJSX(config)
// → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />
Supports bar, line, area, point, rect, arc, tick marks with encoding translation for color, size, aggregation, and binning.
Conversation Arc Telemetry
Capture and replay the path an AI-assisted chart session took:
import {
createLocalStorageConversationArcSink,
enableConversationArc,
getConversationArcStore,
loadConversationArc,
registerConversationArcSink,
} from "semiotic/ai"
const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
registerConversationArcSink(sink)
enableConversationArc({ sessionId: "session-abc" })
getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
loadConversationArc(sink.load(), { enabled: false })
What's New in 3.13.3
3.13.3 improves streaming chart suggestions with field cardinality, additivity, and schema warnings, and adds count aggregation for realtime histograms. Streaming charts preserve extents, hover detail, and keyboard focus as data changes. Pie, donut, and network charts use more of their available space, with matching server rendering. This release also improves chart error recovery, legend fitting, heatmap colors, and compositional routing.
See the changelog for the complete fixes and additions.
Why Semiotic
Semiotic is a data visualization library for React that combines broad chart coverage with AI tooling. It supports network graphs, streaming data, statistical distributions and coordinated views, with schemas, examples and diagnostics for implementing and checking each task. Check the project's existing dependencies first: extending its current charting library may be the best fit for a small change.
Built for AI-assisted development
Semiotic provides a workflow for generating, checking and repairing chart configurations. The July 27, 2026 evaluation reports model- and task-specific results; it does not guarantee first-try correctness.
semiotic/ai— a single import with the schema-backed chart capability catalog (XY, ordinal, network, realtime, geo, value, and portable recipes), optimized for LLM code generation. Seeai/surface-manifest.jsonfor the generated current inventory. Named imports now tree-shake across published chunks. Prefer family subpaths (semiotic/xy,semiotic/geo,semiotic/value, …) in production code to keep the intended chart family explicit; the cold-consumer table below reports initial-load and on-demand costs.ai/schema.json— machine-readable prop schemas for every componentnpx -y -p semiotic semiotic-mcp— an MCP server for tool-based chart rendering in any MCP clientnpx -p semiotic semiotic-ai --doctor— validate component + props JSON from the command line with typo suggestions and anti-pattern detectiondiagnoseConfig(component, props)— programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checksauditData(component, props, data?)— chart-aware numeric preflight for inputs that pass schema validation but break the math: non-finite values, zero-span domains, invalid log inputs, negative size geometry, unsafe normalized totals, and scale-dominating outliers. Returns bounded row evidence and flows intodiagnoseConfig, Chart Clinic, CLI doctor, and opt-inChartContainernotificationsAGENTS.md— concise repository workflow shared by modern coding agents;CLAUDE.mdimports it and Copilot receives a short compatibility bridgeai/reference.md— complete on-demand product reference, kept out of always-loaded coding-agent contextllms.txt— machine-readable documentation following the emerging standard
Every chart includes a built-in error boundary, dev-mode validation
warnings with typo suggestions, and accessibility features (canvas
aria-label, keyboard-navigable legends, keyboard live-region announcements, SVG
<title>/<desc>) so AI-generated code fails gracefully with
actionable diagnostics instead of a blank screen.
Accessibility is a release surface
The European Accessibility Act has applied to covered products and services since 28 June 2025. A chart library cannot certify an application's legal compliance: scope, content, surrounding controls, testing, and national enforcement remain the application owner's responsibility. Semiotic supplies testable infrastructure for that work: keyboard interaction, accessible data tables, layered descriptions, structured navigation, reduced-motion and forced-colors paths, and WCAG-derived contrast tests for shipped theme presets. See the Accessibility docs and run the application's own assistive-technology and user testing.
Beyond standard charts
Network visualization. Force-directed graphs, Sankey diagrams, chord diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all as React components with the same prop API as LineChart.
Streaming data. Realtime charts render on canvas at 60fps with a ref-based push API. Rapid network edge pushes coalesce into one layout per animation frame, while read/mutation methods preserve synchronous read-after-write semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.
Coordinated views. LinkedCharts provides hover cross-highlighting,
brush cross-filtering, coordinate-based linked crosshairs, and selection
synchronization across any combination of chart types through shared selection state.
Geographic visualization. Choropleth maps, proportional symbol maps, flow maps with animated particles, and distance cartograms — all canvas-rendered with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning.
Statistical summaries. Box plots, violin plots, swarm plots, histograms, LOESS smoothing, forecast with confidence envelopes, and anomaly detection. Marginal distribution graphics on scatterplot axes with a single prop.
First-class annotations. Annotations are data-bound objects, not post-hoc artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and React widgets move with the chart and render through browser, SSR, and export paths. Opt into placement, hierarchy, density, progressive disclosure, audience-aware amount, provenance, and editorial lifecycle when the chart needs to communicate more than its encoding alone.
Choose the API layer
| Layer | For | Example |
|---|---|---|
| Charts | Common chart forms with chart-level props | <LineChart data={d} xAccessor="x" yAccessor="y" /> |
| Frames | Full control over rendering, interaction, and layout | <StreamXYFrame chartType="line" lineStyle={...} /> |
Chart HOCs register only the mark plugins they need. Direct StreamXYFrame
loads the remaining built-ins on first client paint. Call
registerBuiltInXYPlugins() from semiotic/xy or semiotic/realtime/core
before the first render when SSR or the first frame must include marks.
Every Chart component accepts a frameProps prop to access the underlying
Frame API without leaving the simpler interface.
Serialization and interop
Charts serialize to JSON and back: toConfig, fromConfig, toURL,
copyConfig, configToJSX. Have Vega-Lite specs? fromVegaLite(spec)
translates them to Semiotic configs — works with configToJSX() for
full round-trip from notebooks and AI-generated specs.
Need an external pitfall review? The experimental unstable_toDataPitfallsChain() builds a
dependency-free chain input for datapitfalls,
combining the Semiotic config, JSX, reader grounding, diagnostics,
accessibility audit, and optional rendered SVG/image evidence:
import { unstable_toDataPitfallsChain } from "semiotic/experimental"
import { detectPitfalls } from "datapitfalls"
const input = unstable_toDataPitfallsChain("LineChart", props, {
narrative: "Monthly sales are accelerating.",
rendered: { svg, evidence },
})
const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })
The return path stays dependency-free too. Use whole-chart findings as
ChartContainer notifications, and only turn findings into annotations after
your app can anchor them to marks or semantic positions:
import { ChartContainer } from "semiotic"
import { LineChart } from "semiotic/xy"
import {
unstable_toDataPitfallsAnnotations,
unstable_toDataPitfallsNotifications,
} from "semiotic/experimental"
const notifications = unstable_toDataPitfallsNotifications(report)
const annotations = unstable_toDataPitfallsAnnotations(report, {
anchorFor: (finding) =>
finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
})
<ChartContainer notifications={notifications}>
<LineChart {...props} annotations={annotations} />
</ChartContainer>
When to use something else
Need a standard bar or line chart for a dashboard you'll never need to customize beyond colors and labels? Recharts has a larger ecosystem and more community examples. Need GPU-accelerated rendering for millions of data points? Apache ECharts handles that scale.
Semiotic is for projects that outgrow those libraries — when you need network graphs alongside time series, streaming data alongside static snapshots, or coordinated views across chart types.
Semiotic MCP questions
How do I add Semiotic MCP to Claude Code?
Run claude mcp add semiotic -- npx -y semiotic in your terminal. Add --scope user to make it available in every project.
How do I add Semiotic MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Semiotic MCP provide?
It exposes 5 tools, including createChart, improveChart, explainChart, auditChart, getChartSchema.
Does Semiotic support real-time streaming data?
Yes, it includes specialized components like RealtimeLineChart and StreamNetworkFrame designed for live data feeds with features like decay and staleness detection.

