Guide

MCP Server

The MetricUI MCP server gives AI coding tools structured knowledge of every component, every prop, and every pattern — so they generate production-quality dashboards on the first try.

Setup

One command adds MetricUI to your AI tool. The server runs via npx — no global install needed.

Claude Code

claude mcp add --transport stdio metricui -- npx -y @metricui/mcp-server

Cursor / Windsurf

Add to your project's .cursor/mcp.json or equivalent:

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

Global install (optional)

npm install -g @metricui/mcp-server

How It Works

The MCP server exposes MetricUI's full API surface through the Model Context Protocol. When your AI tool connects, it receives:

Server instructions— what MetricUI is, what makes it different, and how to build dashboards the right way
13 tools— generate dashboards, look up APIs, validate props, search docs, scaffold configs
9 resources— full component catalog, config reference, format engine, theming, TypeScript types, usage patterns
4 prompts— guided workflows for building, reviewing, and migrating dashboards

The AI doesn't guess at APIs or generate generic chart code. It knows every prop, every data shape, every advanced feature — and uses them. DashboardHeader, MetricGrid, conditions, goals, reference lines, threshold bands, filters, theme presets.

Tools

Tools are callable functions the AI invokes to look up APIs, generate code, and validate its work.

`generate_dashboard`

Generates a complete, production-quality dashboard page with realistic sample data. Uses MetricProvider with theme presets, FilterProvider + PeriodSelector, DashboardHeader with live status, MetricGrid auto-layout, advanced KpiCards (conditions, goals, sparkline overlays), charts with reference lines and threshold bands, data-driven Callout alerts, and rich DataTable.

Parameter	Type	Required	Description
`description`	`string`	Yes	What the dashboard should show. E.g., 'SaaS metrics with MRR, churn, users, and revenue breakdown'
`theme`	`enum`	No	Theme preset: indigo, emerald, rose, amber, cyan, violet, slate, orange
`style`	`enum`	No	'dense' or 'spacious'
`variant`	`enum`	No	'default', 'outlined', 'ghost', or 'elevated'
`metrics`	`string[]`	No	Specific metrics to include

Returns a full page.tsxfile — imports, sample data, and component tree — ready to paste into your project. Detects keywords in the description to include specialized components: "funnel" adds Funnel, "gauge" adds Gauge, "waterfall" adds Waterfall.

`get_component_api`

Returns the full API reference for any component — every prop with type, default, and description. Includes data shape, minimal example, advanced examples, MetricConfig fields, and usage notes.

Parameter	Type	Required	Description
`component`	`string`	Yes	Component name. E.g., 'KpiCard', 'AreaChart', 'DataTable'

`get_component_example`

Returns a complete, working code example for a component with requested features enabled. Uses realistic sample data and annotates every prop. The AI adapts the values — the structure is correct as-is.

Parameter	Type	Required	Description
`component`	`string`	Yes	Component name
`features`	`string[]`	No	Features to showcase: 'comparison', 'sparkline', 'goal', 'conditions', 'referenceLines', 'thresholds', 'stacked', 'grouped', 'horizontal', 'footer', 'pagination'

`search_docs`

Search all MetricUI documentation — components, props, types, patterns, format examples, and guides. Returns ranked results with snippets. Best for conceptual questions like 'how do I set up dark mode?' or 'what format for currency?'

Parameter	Type	Required	Description
`query`	`string`	Yes	Natural language query. E.g., 'dark mode setup', 'table pagination', 'reference lines'
`limit`	`number`	No	Max results (default: 5)
`type`	`enum`	No	Filter by: 'component', 'prop', 'type', 'pattern', 'guide', 'format', or 'all'

`search_components`

Find the right component for a use case. Searches by name, description, and props. Returns ranked results.

Parameter	Type	Required	Description
`query`	`string`	Yes	Natural language. E.g., 'show revenue over time', 'pie chart', 'status health check'

`validate_props`

Validates a component's prop configuration. Catches unknown props, missing required props, deprecated usage, and common mistakes like using sparklineData instead of sparkline.

Parameter	Type	Required	Description
`component`	`string`	Yes	Component name
`props`	`object`	Yes	Props to validate as key-value pairs

`suggest_format`

Suggests the right format configuration for a value type. Handles revenue, percentages, durations, counts, and more.

Parameter	Type	Required	Description
`valueType`	`string`	Yes	What kind of value: 'revenue', 'percentage', 'time', 'count'
`sampleValue`	`number`	No	A sample value to show formatted output

`generate_table_columns`

Generates DataTable column definitions from a list of fields. Automatically applies format, alignment, and sortable based on field type.

Parameter	Type	Required	Description
`fields`	`object[]`	Yes	Array of { key, label?, type: 'string'\|'number'\|'currency'\|'percent'\|'date'\|'boolean', sortable? }

`generate_provider_config`

Generates MetricProvider configuration JSX with only the fields you need.

Parameter	Type	Required	Description
`locale`	`string`	No	BCP 47 locale
`currency`	`string`	No	ISO 4217 currency code
`animate`	`boolean`	No	Animation toggle
`variant`	`string`	No	Card variant
`dense`	`boolean`	No	Dense mode
`nullDisplay`	`string`	No	Null display strategy

`generate_data_shape`

Generates the TypeScript interface for a component's required data shape.

Parameter	Type	Required	Description
`component`	`string`	Yes	Component name
`series`	`string[]`	No	Series/field names to include

`get_setup_guide`

Returns complete setup instructions — install commands, peer dependencies, provider setup, CSS imports, and framework-specific config.

Parameter	Type	Required	Description
`framework`	`enum`	No	'nextjs', 'vite', 'cra', 'remix', or 'generic' (default: nextjs)

`init_project`

Generates CLAUDE.md content for your project so AI tools always use MetricUI components. Run once per project.

`list_components`

Lists all MetricUI components with name, category, description, and prop count.

Parameter	Type	Required	Description
`category`	`enum`	No	Filter by: 'chart', 'card', 'table', or 'ui'

Resources

Resources are read-only data the AI can pull into its context. These provide deep reference material that's too large for tool responses.

Static Resources

URI	Description
`metricui://catalog`	Complete list of all components with descriptions and import statement
`metricui://config`	MetricProvider & MetricConfig — all fields, defaults, nesting, hooks, resolution order
`metricui://format`	Format engine — shorthand strings, FormatConfig objects, fmt() helper, compact modes, duration styles
`metricui://theming`	CSS variables, card variants, semantic colors, texture control, dense mode, dark mode, motion config
`metricui://types`	All TypeScript types exported by MetricUI — FormatOption, ComparisonConfig, Condition, Column, etc.
`metricui://patterns`	Usage patterns and code recipes — full dashboards, KPI features, data fetching, conditional formatting, theme presets, reference lines, filter system, responsive layout

Resource Templates

Dynamic resources that accept a parameter to return specific items:

URI Template	Description
`metricui://components/{name}`	Full API reference for a specific component — props table, data shape, examples, notes
`metricui://types/{name}`	TypeScript definition for a specific type — full interface, related types
`metricui://patterns/{slug}`	Specific usage pattern — description, tags, complete code example

Prompts

Prompts are guided workflows the AI can invoke. They inject structured context and instructions for specific tasks.

build_dashboard

Guided dashboard creation from a description. Injects the full component selection guide (26 components organized by use case), architecture rules (MetricProvider, FilterProvider, DashboardHeader, MetricGrid), advanced feature tips (conditions, goals, reference lines, threshold bands, Callout rules), and format mapping.

Parameter: description — what the dashboard should show

review_dashboard

Reviews existing MetricUI code for errors (missing required props, wrong data shapes), deprecations (sparklineData → sparkline, compact → dense, grouped → groupMode), best practices (missing MetricProvider, unformatted values, missing data states), and accessibility issues.

Parameter: code — the MetricUI code to review

convert_dashboard

Converts a screenshot, mockup, wireframe, or hand-drawn sketch into MetricUI code. Paste an image in chat, then invoke this prompt. The AI identifies visual elements (KPI cards, charts, tables, filters), maps them to MetricUI components, infers theme/format/layout, and generates a complete working dashboard.

Parameter: description (optional) — additional context about the image

migrate_to_metricui

Migrates dashboard code from another library (Tremor, Recharts, shadcn, Chart.js) to MetricUI. Includes component mapping tables, data shape differences, and key migration steps.

Parameters: source_library, code

llms.txt

For AI tools that don't support MCP, MetricUI serves a machine-readable documentation file at /llms.txt. This is a plain text file containing every component, every prop, every type, and every pattern — formatted for LLM consumption.

AI tools can fetch this file to gain full knowledge of MetricUI's API without needing a persistent MCP connection. The MCP server is more powerful (interactive tools, validation, generation), but llms.txt provides a solid baseline for any AI that can read URLs.