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

• 16 Essential Tools for Material 3 development (including Context7 integration, RAG database, AI-powered design, and motion system)
• 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
• Context7 integration: Search and retrieve documentation for any library using Context7 API
• RAG Database: Dual-memory vector database with declarative and procedural memory
• AI-Powered Design Tools: Theme extraction from images, UI auditing, sketch-to-code conversion
• MD3 Motion System: Analyze transitions and generate code with official bezier curves and duration tokens

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

Local Development

For local development or running from source:

1. Clone and install:

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

2. Create .env file:

cp .env.example .env

3. Configure environment variables in .env:

# Google AI API (required for design tools, motion, architect)
GOOGLE_API_KEY=your_google_api_key_here

# GitHub Token (optional - for higher rate limits)
GITHUB_TOKEN=your_github_token_here

# Model Configuration (optional - defaults shown)
GEMINI_DESIGN_MODEL=gemini-1.5-flash
GEMINI_MOTION_MODEL=gemini-1.5-flash
GEMINI_ARCHITECT_MODEL=gemini-2.5-pro

# RAG Database Models (optional)
GOOGLE_GENERATION_MODEL=gemini-1.5-flash
GOOGLE_EMBEDDING_MODEL=text-embedding-004

# Ollama (optional - for local embeddings)
OLLAMA_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest

# Logging
LOG_LEVEL=INFO

4. Configure your MCP client to use the local build:

Claude Desktop:

{
  "mcpServers": {
    "material3-local": {
      "command": "node",
      "args": ["/absolute/path/to/material3-mcp-server/build/index.js"],
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Cursor IDE:

{
  "mcpServers": {
    "material3-local": {
      "command": "node",
      "args": ["/absolute/path/to/material3-mcp-server/build/index.js"]
    }
  }
}

5. Verify configuration on startup:
   When the server starts, it will log all loaded configuration:

Configuration loaded {
  googleAPI: 'configured',
  githubToken: 'configured',
  ollama: 'configured',
  designModel: 'gemini-1.5-flash (default)',
  motionModel: 'gemini-1.5-flash (default)',
  architectModel: 'gemini-2.5-pro (default)',
  logLevel: 'INFO (default)'
}

Available Tools

Core Material 3 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"

6. manage_cache_health

Manage cache health and verify data integrity.

Parameters:

• action: check-status, verify-upstream, invalidate, clear-all
• category (optional): docs, github, icons

Example usage:

"Check cache status"
"Verify upstream changes"

7. generate_theme_from_color

Generate complete Material 3 color palette from a single base color.

Parameters:

• baseColor: Hex color code (e.g., ‘#6750A4’)
• format (optional): css, scss, json, javascript

Example usage:

"Generate a Material 3 theme from #FF5722"
"Create color tokens from purple"

8. suggest_components_for_use_case

Get AI-powered component suggestions based on use case description.

Parameters:

• useCase: Description of what you want to build
• framework (optional): web, flutter

Example usage:

"Suggest components for a user profile page"
"What components do I need for a shopping cart?"

Context7 Integration Tools

9. search_libraries

Search for libraries and documentation using the Context7 API.

Parameters:

• query: Search query (e.g., ‘react’, ‘material design’)

Example usage:

"Search for Material Web libraries"
"Find React documentation"

10. get_library_docs

Fetch detailed documentation for a specific library from Context7.

Parameters:

• libraryId: Context7 library ID (e.g., ‘/material-components/material-web’)
• topic (optional): Specific topic to focus on
• tokens (optional): Max tokens to return (default: 10000)

Example usage:

"Get documentation for /material-components/material-web"
"Fetch Next.js routing docs"

RAG Database Tool

11. database_tool

Vector-based RAG database with dual-memory architecture for storing and retrieving documentation.

Actions:

Standard Operations

• store – Store documents with vector embeddings
• generate – AI-powered document generation and storage
• query – Semantic search for documents
• delete – Remove documents by ID
• list – List all documents

Declarative Memory (Facts/Events)

• save_declarative – Store facts with sources (like hippocampus)
• recall_declarative – Semantic recall of facts

Procedural Memory (Skills/Workflows)

• save_procedural – Learn workflows and procedures (like basal ganglia)
• recall_procedural – Execute learned procedures

Parameters:

• action: One of the 9 actions above
• id: Document ID (for store/delete)
• content: Document content or fact
• source: Source for declarative memory
• goal: Goal description for procedural memory
• steps: Array of workflow steps
• query: Search query
• prompt: Generation prompt
• limit: Result limit (default: 5)

Example usage:

"Store Material 3 button guidelines as a document"
"Save fact: Material 3 uses dynamic color with source: m3.material.io"
"Learn procedure: how to create a themed component with steps: [...]"
"Query the database for theming information"
"Recall procedures for implementing accessibility"

AI-Powered Design Tools

12. md3_extract_theme

Extract semantic seed color from images using Gemini vision and generate scientifically accurate HCT Material Design 3 themes.

Parameters:

• image: Base64 encoded image string (JPEG or PNG)
• context (optional): Context about the app (e.g., “Eco-friendly banking app”) to influence color selection

Returns:

• Extracted seed color (hex)
• Source analysis from Gemini
• Complete light and dark color schemes
• Tonal palettes (primary, secondary, tertiary at different tones)

Example usage:

"Extract a Material 3 theme from this app screenshot"
"Generate theme from this brand logo for a fitness app"

13. md3_audit_ui

Expert critique of UI screenshots against Material Design 3 guidelines.

Parameters:

• image: Base64 encoded screenshot of a UI

Analyzes:

1. Elevation & Surface: Shadow usage vs tonal surface fills
2. Hierarchy: Primary, Secondary, and Tertiary action distinction
3. Spacing & Layout: 4dp/8dp grid system adherence
4. Accessibility: Contrast issues and touch target sizes

Returns: Structured violations and recommendations

Example usage:

"Audit this Material 3 app screen for design compliance"
"Check if this UI follows MD3 elevation guidelines"

14. md3_sketch_to_code

Convert hand-drawn wireframes to production-ready HTML using Material Web 3 components.

Parameters:

• image: Base64 encoded image of hand-drawn sketch or wireframe

Generates:

• HTML structure using <md-*> custom elements
• Proper Material Web components (buttons, lists, text fields, icons, cards)
• Production-ready code with semantic structure

Example usage:

"Convert this wireframe sketch to Material Web code"
"Turn this napkin sketch into working HTML with MD3 components"

MD3 Motion System

15. md3_analyze_flow

Determine the correct Material Design 3 transition pattern based on before/after UI states.

Parameters:

• start_image: Base64 screenshot of UI state BEFORE interaction
• end_image: Base64 screenshot of UI state AFTER interaction
• description: What is the user doing? (e.g., “Clicking a list item to see details”)

Analyzes and recommends:

1. Container Transform: Element grows into larger surface (FAB → Menu, Card → Page)
2. Shared Axis: Elements move on X/Y/Z axis (Steppers, Tabs)
3. Fade Through: Major relationship change (Bottom Nav switching)
4. Fade: Simple entry/exit
5. Duration Token: Short/Medium/Long based on pixel distance

Example usage:

"Analyze the transition from clicking a list item to viewing its details"
"What MD3 motion pattern should I use for expanding a card to full screen?"

16. md3_generate_transition

Generate production-ready transition code with exact MD3 bezier curves and duration tokens.

Parameters:

• pattern: container-transform, shared-axis-x/y/z, fade-through, elevation-scale
• tech_stack: css, framer-motion, web-animations-api, angular
• direction: forward (enter) or backward (exit/return)
• element_selector (optional): CSS selector for target element

Uses official MD3 constants:

• Easing curves:
  • Emphasized: cubic-bezier(0.2, 0.0, 0.0, 1.0)
  • Emphasized Decelerate: cubic-bezier(0.05, 0.7, 0.1, 1.0) (entering)
  • Emphasized Accelerate: cubic-bezier(0.3, 0.0, 0.8, 0.15) (exiting)
  • Standard: cubic-bezier(0.2, 0.0, 0, 1.0)
• Duration tokens: 100ms-500ms (short1 to long2)

Example usage:

"Generate CSS for a container-transform transition entering forward"
"Create Framer Motion code for shared-axis-x transition exiting backward"
"Generate Web Animations API code for fade-through with .modal selector"

## Environment Variables

### Core Settings
- `GITHUB_TOKEN` (optional): For increased GitHub API rate limits
- `LOG_LEVEL` (optional): DEBUG, INFO, WARN, ERROR (default: INFO)
- `GOOGLE_API_KEY` (required for AI tools): Required for:
  - Document generation (RAG database)
  - Embedding fallback (RAG database)
  - Theme extraction from images (md3_extract_theme)
  - UI auditing (md3_audit_ui)
  - Sketch-to-code conversion (md3_sketch_to_code)
  - Get one at: https://aistudio.google.com/app/apikey

### Database & Embeddings
The RAG database uses a fallback system for embeddings:
1. **Primary**: Ollama with `nomic-embed-text:latest` (local, free, private)
2. **Fallback**: Google `text-embedding-004` (requires `GOOGLE_API_KEY`)

To use Ollama (recommended):
```bash
# Pull the embedding model
ollama pull nomic-embed-text:latest
# Or use embeddinggemma
ollama pull embeddinggemma:latest

Context7 Integration

The server now integrates with Context7 for enhanced documentation retrieval:

• Documentation is fetched from Context7 API (https://context7.com/api)
• Material Web components now include real descriptions from /material-components/material-web
• Two new tools (search_libraries and get_library_docs) provide access to any library in Context7

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/           # 10 MCP tools
│   ├── providers/       # Data providers with Context7 integration
│   ├── utils/           # Logger, validators, and Context7 client
│   ├── 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 ✅
• Context7 integration for enhanced documentation ✅
• RAG Database with dual-memory architecture ✅
• AI-Powered MD3 Design Tools (theme extraction, UI audit, sketch-to-code) ✅
• MD3 Motion System (transition analysis and code generation) ✅
• 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