Material 3 MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Material 3 MCP Server List all Material 3 button components"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Material 3 MCP Server
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
Getting Started Guide - Complete setup in < 5 minutes
API Reference - Detailed tool documentation
Troubleshooting - Common issues and solutions
Usage Examples - Real-world workflows
Installation
NPM (Recommended)
npm install -g @weppa-cloud/material3-mcp-serverFrom Source
git clone <repository-url>
cd material3-mcp-server
npm install
npm run buildVerify installation:
./scripts/test-package.shConfiguration
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, allcomplexity(optional): simple, medium, complex, allframework(optional): web, flutter, react, angular, allincludeDeprecated(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/flutterGitHub repoβ Web: Fetches TypeScript/JavaScript from
material-components/material-webrepoπ 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, allformat(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, sharpfilled(optional): booleanlimit(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 namewcagLevel(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 devBuild
npm run buildTest with MCP Inspector
npm run inspectorThis 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.jsonRoadmap
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:
β Update version in
package.jsonβ Run tests and build
β Commit and create git tag
β Push to GitHub
β Create GitHub Release
β 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:
Generate NPM token: https://www.npmjs.com/settings/weppa-cloud/tokens (Automation type)
Add to GitHub: https://github.com/weppa-cloud/material3-mcp-server/settings/secrets/actions
Name:
NPM_TOKEN, Value: your token
See RELEASE.md for detailed instructions.
License
MIT
Author
weppa-cloud
Links
Available Tools
8 toolsgenerate_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Give AI agents your deeepSpace design system: components, tokens, styles and code mappings.
Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Design systems your AI agent builds with and you reshape, plus standalone React components.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides AI assistants with tools to grade, generate, and validate UI components against the components.build specification. Supports searching documentation, checking compliance, and generating framework-agnostic accessible components.1121 npmApache 2.0
- FlicenseNot gradedqualityNot gradedmaintenanceProvides AI assistants with 6 tools to access Material UI component documentation, enabling consistent and well-designed React application development.-
- AlicenseAqualityBmaintenanceProvides deterministic, read-only design knowledge for AI coding agents to help them choose visual directions, plan UI states, and compose design tokens, all without network access.6250 npm29MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with component documentation, usage examples, and design tokens from the WordPress Design System, enabling them to follow the latest design system guidance for creating user interfaces.384 npmGPL 2.0