mui

Detection Signals

• @mui/material in package.json
• @emotion/react and @emotion/styled dependencies
• ThemeProvider, createTheme imports in codebase
• CssBaseline component at app root
• sx prop usage on components

MCP Setup

MUI has an official MCP server for component docs, prop references, examples, and theming.

Add to .claude/settings.json:

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

If auto-configuration fails, ask the user to add the entry manually in their CLI's MCP settings (Claude Code → Settings → MCP Servers, the mcp block of opencode.json, or Codex CLI's MCP config). The MCP provides real-time component API access without leaving the editor.

Core Concepts

Concept	Detail
ThemeProvider	Wraps the app; all components read theme tokens from it
sx prop	Inline styling via theme tokens — preferred over style or CSS classes
createTheme()	Extends/overrides Material Design defaults
Emotion	CSS-in-JS engine used internally — don't mix with other CSS-in-JS libs
Breakpoints	xs (0px), sm (600px), md (900px), lg (1200px), xl (1536px)
useTheme()	Access theme tokens inside component logic

Component Patterns

// sx prop — use theme tokens, not raw values
<Box sx={{ p: 2, bgcolor: 'background.paper', borderRadius: 1 }}>

// Responsive values via sx
<Typography sx={{ fontSize: { xs: '1rem', md: '1.25rem' } }} />

// Theme extension — brand decisions belong here, not in CSS files
const theme = createTheme({
  palette: { primary: { main: '#1976d2' } },
  typography: { fontFamily: '"Inter", sans-serif' },
})

// Grid2 (v5+) — the deprecated Grid has been replaced
import Grid from '@mui/material/Grid2'
<Grid container spacing={2}>
  <Grid size={6}><Item /></Grid>
</Grid>

Critical Rules

• ThemeProvider is mandatory at app root — components without it fall back to defaults and look inconsistent
• Use sx over style — sx resolves theme tokens, breakpoints, and pseudo-selectors; style does not
• Extend via createTheme() — put all brand decisions there, not in global CSS overrides
• Use Grid2 (not the legacy Grid) in MUI v5+
• Check MUI version before writing code — v5 and v6 have significant API differences; look at package.json
• Never mix Emotion with other CSS-in-JS — style conflicts are hard to debug and runtime cost doubles