Skip to main content
Glama
Material 3 MCP Server

Material 3 MCP Server

by weppa-cloud

Material 3 MCP Server

CI npm version License: MIT

MCP server providing AI agents with convenient access to Material 3 design system components, design tokens, icons, and accessibility guidelines across multiple frameworks.

Features

  • 5 Essential Tools for Material 3 development

  • Multi-framework support:

    • βœ… Web Components (Material Web - fully supported)

    • βœ… Flutter (Flutter Material - fully supported)

    • πŸ”œ React, Angular (coming soon)

  • Accessibility-first: WCAG 2.1 guidelines for every component

  • Design tokens: Export in CSS, SCSS, JSON, or JavaScript

  • Icon search: Access to 2,500+ Material Symbols

Related MCP server: mui-mcp-cloudflare

Quick Start

πŸ“š Documentation

Installation

npm install -g @weppa-cloud/material3-mcp-server

From Source

git clone <repository-url>
cd material3-mcp-server
npm install
npm run build

Verify installation:

./scripts/test-package.sh

Configuration

Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "material3": {
      "command": "npx",
      "args": ["-y", "@weppa-cloud/material3-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_optional",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Cursor IDE

Add to Cursor settings (~/.cursor/config/mcp.json):

{
  "mcpServers": {
    "material3": {
      "command": "npx",
      "args": ["-y", "@weppa-cloud/material3-mcp-server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Available Tools

1. list_material_components

List Material 3 components with filters.

Parameters:

  • category (optional): buttons, cards, chips, dialogs, lists, menus, navigation, progress, selection, sliders, text-fields, all

  • complexity (optional): simple, medium, complex, all

  • framework (optional): web, flutter, react, angular, all

  • includeDeprecated (optional): boolean

Example usage:

"List all Material 3 button components"
"Show me simple components for React"

2. get_component_code

Get real source code for Material 3 components.

Parameters:

  • componentName: Component name (e.g., 'button', 'card', 'text-field')

  • framework (optional): web, flutter (default: flutter). React and Angular coming soon.

  • variant (optional): Variant name (e.g., 'filled', 'outlined', 'elevated')

  • includeExamples (optional): boolean (default: true)

  • includeDependencies (optional): boolean (default: true)

Supported Frameworks:

  • βœ… Flutter: Fetches Dart code from flutter/flutter GitHub repo

  • βœ… Web: Fetches TypeScript/JavaScript from material-components/material-web repo

  • πŸ”œ React, Angular: Planned for future releases

Example usage:

"Get code for a Material 3 button" β†’ Returns Flutter code (default)
"Get code for an elevated button in Flutter"
"Show me the card component code for web"
"Get outlined button code for Flutter with examples"

3. get_design_tokens

Export Material 3 design tokens in multiple formats.

Parameters:

  • tokenType (optional): color, typography, spacing, elevation, shape, motion, all

  • format (optional): css, scss, json, javascript (default: json)

  • includeDocumentation (optional): boolean (default: true)

Example usage:

"Get Material 3 color tokens in CSS format"
"Export all design tokens as JSON"

4. search_material_icons

Search Material Symbols icon library.

Parameters:

  • query: Search query (e.g., 'home', 'settings')

  • style (optional): outlined, rounded, sharp

  • filled (optional): boolean

  • limit (optional): number (max 100, default 20)

Example usage:

"Search for home icons in Material Symbols"
"Find navigation icons"

5. get_accessibility_guidelines

Get WCAG 2.1 accessibility guidelines for components.

Parameters:

  • componentName: Component name

  • wcagLevel (optional): A, AA, AAA (default: AA)

  • includeARIA (optional): boolean (default: true)

  • includeKeyboard (optional): boolean (default: true)

Example usage:

"What are the accessibility guidelines for Material 3 buttons?"
"Get WCAG AAA guidelines for text fields"

Environment Variables

Core Settings

  • GITHUB_TOKEN (optional): GitHub personal access token for higher API rate limits (5,000/hour vs 60/hour)

  • LOG_LEVEL (optional): DEBUG, INFO, WARN, ERROR (default: INFO)

Web Scraping (Future Feature)

The following environment variables will be used for the upcoming web scraping feature (see PRPs/web-scraping-quick-wins.md):

  • ENABLE_WEB_SCRAPING (optional): Enable web scraping from m3.material.io (default: false)

  • WEB_SCRAPING_RATE_LIMIT (optional): Maximum requests per second for web scraping (default: 10)

  • HTTP_TIMEOUT (optional): HTTP request timeout in milliseconds (default: 5000)

  • HTTP_RETRY_ATTEMPTS (optional): Number of retry attempts for failed requests (default: 3)

  • CACHE_TTL (optional): Cache time-to-live in seconds (default: 3600)

  • CACHE_CHECK_PERIOD (optional): Cache cleanup interval in seconds (default: 600)

  • MIN_COMPONENTS_THRESHOLD (optional): Minimum number of components for healthy cache (default: 15)

Development

Run in Development Mode

npm run dev

Build

npm run build

Test with MCP Inspector

npm run inspector

This opens a web interface at http://localhost:6274 where you can test all tools interactively.

Success Metric

The agent can use the tools conveniently to implement features using Material 3 guidelines.

Testing

The server has been designed to be tested with MCP Inspector following the official MCP guidelines. All tools return structured JSON responses that can be easily consumed by AI agents.

Architecture

material3-mcp-server/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ tools/           # 5 MCP tools
β”‚   β”œβ”€β”€ providers/       # Data providers (no cache for MVP)
β”‚   β”œβ”€β”€ utils/           # Logger and validators
β”‚   β”œβ”€β”€ types/           # TypeScript types
β”‚   └── index.ts         # Entry point
β”œβ”€β”€ build/               # Compiled output
└── package.json

Roadmap

  • Real GitHub API integration for live component code βœ…

  • Material Symbols API integration (Iconify JSON) βœ…

  • Cache system for optimized performance βœ…

  • Unit testing with Vitest βœ…

  • CI/CD with GitHub Actions βœ…

  • Web scraping for m3.material.io documentation (optional)

  • Flutter documentation integration

  • Figma integration (optional)

Release & Publishing

This project uses automated NPM publishing via GitHub Actions.

For Maintainers

Quick Release

./scripts/release.sh 1.2.0 "New features and improvements"

The script will:

  1. βœ… Update version in package.json

  2. βœ… Run tests and build

  3. βœ… Commit and create git tag

  4. βœ… Push to GitHub

  5. βœ… Create GitHub Release

  6. βœ… Trigger automatic NPM publish via GitHub Actions

Manual Release

# Update version in package.json manually
git add package.json
git commit -m "chore: bump version to 1.2.0"
git tag v1.2.0
git push && git push --tags
gh release create v1.2.0 --title "v1.2.0" --notes "Release notes..."

First-time Setup

To enable automatic NPM publishing, configure the NPM_TOKEN secret:

  1. Generate NPM token: https://www.npmjs.com/settings/weppa-cloud/tokens (Automation type)

  2. Add to GitHub: https://github.com/weppa-cloud/material3-mcp-server/settings/secrets/actions

  3. Name: NPM_TOKEN, Value: your token

See RELEASE.md for detailed instructions.

License

MIT

Author

weppa-cloud

Available Tools

8 tools
generate_theme_from_colorGenerate Theme from ColorB

Generate complete Material 3 color palette from a single base color

Inputs: baseColor (required), mode, format, contrastLevel.

get_accessibility_guidelinesGet Accessibility GuidelinesB

Get WCAG 2.1 accessibility guidelines specific to a Material 3 component

Inputs: componentName (required), wcagLevel, includeARIA, includeKeyboard.

get_component_codeGet Component CodeB

Retrieve real source code of specific Material 3 component with variants and examples

Inputs: componentName (required), variant, framework, includeExamples, +1 more.

get_design_tokensGet Design TokensB

Export Material 3 design tokens in multiple formats (CSS, SCSS, JSON, JavaScript)

Inputs: format, tokenType, includeDocumentation.

list_material_componentsList Material 3 ComponentsB

List available Material 3 components with filtering by category, complexity, and framework

Inputs: category, framework, complexity, includeDeprecated.

manage_cache_healthManage Cache HealthB

Check cache status, verify upstream changes, and invalidate stale data

Inputs: action (required), framework, componentName.

search_material_iconsSearch Material IconsB

Search Material Symbols icon library with filters and get usage code for different frameworks

Inputs: query (required), limit, style, filled.

suggest_components_for_use_caseSuggest Components for Use CaseA

Get AI-powered component suggestions based on use case description

Inputs: useCase (required), framework.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of Material 3: component discovery, code retrieval, design tokens, icon search, accessibility, theme generation, cache management, and component suggestions. Even the seemingly overlapping list and suggest tools are clearly separated by purposeβ€”catalog filtering vs. use-case-based recommendations.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (list_, get_, search_, generate_, manage_, suggest_). Verbs are descriptive and uniform, making the API predictable and easy to navigate.

    Tool Count5/5

    With 8 tools, the server is well-scoped for a Material 3 design resource. Each tool covers a fundamental need without redundancy, and the count falls comfortably within the ideal 3-15 range.

    Completeness5/5

    The tool surface comprehensively covers Material 3 design workflows: exploring components, retrieving code and tokens, finding icons, checking accessibility, generating themes, and even providing AI-driven suggestions. The cache management tool is a sensible operational addition, and no obvious core capability is missing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers