Write better CSS with an MDN-aware helper

Tools

Claude Code

Overview

An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN and comprehensive CSS code analysis.

Workflow

An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN and comprehensive CSS code analysis. Features Documentation & Compatibility: Official MDN Docs - Fetches documentation directly from MDN's API Browser Compatibility - Includes browser support data from MDN's BCD Simple API - Just pass CSS property names like "grid", "flexbox", or ":has" Markdown Conversion - Converts HTML documentation to clean, readable markdown Auto-normalization - Supports both simple slugs ("grid") and full paths ("Web/CSS/grid") Smart Caching - SQLite-based cache with 7-day TTL for blazing-fast responses CSS Analysis: 150+ Metrics - Comprehensive analysis of stylesheet quality and complexity Design Patterns - Detect color palettes, font sizes, spacing patterns Code Quality - Selector complexity, specificity analysis, property usage Performance Insights - Identify overly complex selectors and redundant code Installation For Claude Code Install via the Claude Code CLI: For VS Code One click install: Install via VS Code CLI: For MCP Clients (Claude Desktop, etc.) Add to your MCP settings configuration: For Development Or use with npx: Requirements Node.js 20+ Build tools for native modules (usually pre-installed on most systems) Usage Available Tools Fetch CSS documentation for any property, selector, function, or concept. Parameters: slug (string) - CSS feature name or MDN path Examples: Returns: Fetch browser compatibility data for CSS features. Parameters: bcd_id (string) - Browser Compat Data ID (e.g., "css.properties.grid") Example: Analyze CSS code for quality, complexity, and design patterns. Returns curated summary by default (lightweight, ~1-2k tokens). Use summaryOnly: false for complete 150+ metrics (uses ~10k+ tokens). Parameters: css (string, required) - CSS code to analyze summaryOnly (boolean, optional) - Return summary instead of full analysis. Default: true Examples: Returns (default summary): Analyze all CSS files in a project. Finds CSS files recursively, combines them, and provides project-wide analysis. Framework-agnostic - works with built CSS from any framework (SvelteKit, React, Vue, etc.). Returns curated summary metrics by default (lightweight, ~1-2k tokens). Use includeFullAnalysis: true for complete data (uses ~10k+ tokens). Automatically excludes: **/node_modules/** **/*.min.css Parameters: path (string, required) - File path, directory, or glob pattern includeFullAnalysis (boolean, optional) - Return full 150+ metrics instead of summary. Default: false exclude (array of strings, optional) - Additional glob patterns to exclude Examples: Returns (default summary): Cache Management The server automatically: Creates cache at ~/.cache/css-mcp/cache.db Cleans up expired entries on startup Tracks hit counts for each cached entry Uses WAL mode for better concurrent performance To clear the cache: Self-Test Verify the server is working correctly: Expected output: Example: Using with Claude Code Once configured, you can ask Claude Code: Documentation & Compatibility: "Use the CSS MCP to get documentation for flexbox" "What browser support does :has selector have?" "Explain how CSS grid works" CSS Analysis: "Analyze this CSS and tell me what could be improved" "What colors are used in my stylesheet?" "Check the complexity of my selectors" Project Analysis: "Analyze all CSS in my dist folder" "What's the total complexity of my project's CSS?" "Show me all colors used across my entire project" Claude will automatically use the MCP to fetch the latest MDN documentation and analyze CSS code. Development Performance & Limits Caching: First fetch: ~400-500ms (network + cache write) Cached fetch: ~100ms (~5x faster) Cache size: ~390KB for typical usage Input Limits: Max file size: 10MB per CSS file Max total size: 50MB combined Max files: 500 CSS files per analysis Network timeout: 10 seconds for MDN API calls Troubleshooting "Module did not self-register" This usually means native modules need rebuilding: Cache not working Check cache directory permissions: Should show cache.db, cache.db-shm, and cache.db-wal files. Contributing This is an experimental MCP server for CSS documentation tooling, let's work on tools that make AI better at CSS

Reported result

The source does not report measured business outcomes or success metrics for this workflow. It only describes the tool's capabilities, such as caching performance (~100ms for cached fetches) and analysis depth (150+ metrics). A measurable acceptance check would be verifying that the agent correctly retrieves MDN data for a specific CSS property and identifies a known complexity issue in a test stylesheet.

Human role

The original post does not say how a person stayed involved.

Limitations

Requires Node.js 20+ and build tools for native modules. The server is experimental, and network timeouts are set to 10 seconds for MDN API calls. Input limits include a max file size of 10MB per CSS file and 50MB combined. Human approval is necessary before applying any code changes suggested by the analysis.

Try it

Act as a CSS developer using Claude Code with the css-mcp server installed. My goal is to audit the CSS in [replaceable: project directory, e.g., ./dist] for complexity and design consistency. First, run a dry analysis on a single sample file [replaceable: path to one CSS file] using the analyze_css tool with summaryOnly: true. Show me the output, specifically highlighting selector complexity and unique colors. Wait for my confirmation before proceeding. If the sample looks correct, run analyze_project_css on the full directory. Do not modify any files. Output the final report in Markdown format with sections for 'High Complexity Selectors', 'Color Palette', and 'Recommended Refactors'. If the MCP server fails to connect, report the error and stop. Ensure no changes are pushed to the repository without my explicit approval.

More cases · Software & development

• Update a code base with Copilot chat and agent mode
• Check code against user intent with review agents and tests
• Build a budgeting app from a single prompt
• Build a mental models framework with a multi-agent dev team
• Build a instant-opening markdown viewer for macOS