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

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-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

• [x] Real GitHub API integration for live component code ✅
• [x] Material Symbols API integration (Iconify JSON) ✅
• [x] Cache system for optimized performance ✅
• [x] Unit testing with Vitest ✅
• [x] 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

Links

• Material 3 Design
• Material Web Components
• Flutter Material 3
• Material Symbols