Back to search
css-mcp
MCP serverGitHub
An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN and comprehensive CSS code analysis.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/stolinski--css-mcp)HTML
<a href="/listings/stolinski--css-mcp"><img src="/api/listings/stolinski--css-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
For Claude Code
Install via the Claude Code CLI:
claude mcp add css -- npx -y css-mcp
For VS Code
One click install:
Install via VS Code CLI:
code --add-mcp '{\"name\":\"css\",\"command\":\"npx\",\"args\":[\"-y\",\"css-mcp\"],\"env\":{}}'For MCP Clients (Claude Desktop, etc.)
Add to your MCP settings configuration:
{
"mcpServers": {
"css": {
"command": "npx",
"args": ["-y", "css-mcp"]
}
}
}For Development
npm install -g css-mcp
Or use with npx:
npx css-mcp --self-test
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 388 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # CSS MCP Server
- 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:
- ```bash
- claude mcp add css -- npx -y css-mcp
- ```
- ### For VS Code
- One click install:
- [](https://vscode.dev/redirect/mcp/install?name=css&config=%7B%22name%22%3A%22css-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22css-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)
- [](https://insiders.vscode.dev/redirect/mcp/install?name=css&config=%7B%22name%22%3A%22css%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22css-mcp%22%5D%2C%22env%22%3A%7B%7D%7D&quality=insiders)
- Install via VS Code CLI:
- ```bash
- code --add-mcp '{\"name\":\"css\",\"command\":\"npx\",\"args\":[\"-y\",\"css-mcp\"],\"env\":{}}'
- ```
- ### For MCP Clients (Claude Desktop, etc.)
- Add to your MCP settings configuration:
- ```json
- {
- "mcpServers": {
- "css": {
- "command": "npx",
- "args": ["-y", "css-mcp"]
- }
- }
- }
- ```
- ### For Development
- ```bash
- npm install -g css-mcp
- ```
- Or use with npx:
- ```bash
- npx css-mcp --self-test
- ```
- ## Requirements
- - Node.js 20+
- - Build tools for native modules (usually pre-installed on most systems)
- ## Usage
- ### Available Tools
- #### `get_docs`
- Fetch CSS documentation for any property, selector, function, or concept.
- **Parameters:**
- - `slug` (string) - CSS feature name or MDN path
- **Examples:**
- ```javascript
- // Simple slugs (auto-normalized)
- get_docs({ slug: "grid" });
- get_docs({ slug: ":has" });
- get_docs({ slug: "flexbox" });
- get_docs({ slug: "@media" });
- get_docs({ slug: "::before" });
- // Full MDN paths also work
- get_docs({ slug: "Web/CSS/grid" });
- get_docs({ slug: "en-US/docs/Web/CSS/border-radius" });
- ```
- **Returns:**
- ```json
- {
- "source": "mdn-doc",
- "slug": "/en-US/docs/Web/CSS/grid",
- "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/grid/index.json",
- "title": "grid",
- "mdn_url": "/en-US/docs/Web/CSS/grid",
- "summary": "The grid CSS property is a shorthand...",
- "body": [
- {
- "type": "prose",
- "title": "Syntax",
- "content": "The **`grid`** property is a shorthand..."
- }
- ]
- }
- ```
- #### `get_browser_compatibility`
- Fetch browser compatibility data for CSS features.
- **Parameters:**
- - `bcd_id` (string) - Browser Compat Data ID (e.g., `"css.properties.grid"`)
- **Example:**
- ```javascript
- get_browser_compatibility({ bcd_id: "css.properties.grid" });
- get_browser_compatibility({ bcd_id: "css.selectors.has" });
- ```
- #### `analyze_css`
- 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:**
- ```javascript
- // Summary mode (default, lightweight)
- analyze_css({
- css: `
- .container {
- display: grid;
- color: #3b82f6;
- }
- `
- });
- // Full analysis with all 150+ metrics
- analyze_css({
- css: "...",
- summaryOnly: false
- });
- ```
- **Returns (default summary):**
- ```json
- {
- "analysis": {
- "stylesheet": {
- "sourceLinesOfCode": 5,
- "size": 72
- },
- "rules": { "total": 1 },
- "selectors": {
- "total": 1,
- "averageComplexity": 1.0,
- "maxComplexity": 1
- },
- "colors": {
- "unique": 1,
- "uniqueColors": ["#3b82f6"]
- }
- },
- "note": "Summary metrics only. Use summaryOnly: false for complete 150+ metrics."
- }
- ```
- #### `analyze_project_css`
- 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:**
- ```javascript
- // Analyze all CSS in a directory (summary - default, lightweight)
- analyze_project_css({ path: "dist" });
- // Full analysis with all 150+ metrics (uses more tokens)
- analyze_project_css({
- path: "dist",
- includeFullAnalysis: true
- });
- // Exclude additional patterns
- analyze_project_css({
- path: "dist",
- exclude: ["**/vendor/**", "**/*.legacy.css"]
- });
- // Analyze specific file
- analyze_project_css({ path: "public/styles.css" });
- // Use glob patterns
- analyze_project_css({ path: "dist/**/*.css" });
- ```
- **Returns (default summary):**
- ```json
- {
- "files": {
- "total": 5,
- "analyzed": 5,
- "errors": 0,
- "list": [
- { "path": "/path/to/style.css", "size": 2048 },
- { "path": "/path/to/theme.css", "size": 1024 }
- ]
- },
- "summary": {
- "stylesheet": {
- "sourceLinesOfCode": 450,
- "size": 12800
- },
- "rules": { "total": 85 },
- "selectors": {
- "total": 120,
- "averageComplexity": 1.4,
- "maxComplexity": 5
- },
- "colors": {
- "unique": 12,
- "uniqueColors": ["#3b82f6", "#10b981", ...]
- },
- "fontSizes": {
- "unique": 8,
- "uniqueSizes": ["1rem", "1.5rem", ...]
- }
- },
- "note": "Summary metrics only. Use includeFullAnalysis: true for complete data."
- }
- ```
- ## 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:
- ```bash
- rm -rf ~/.cache/css-mcp/
- ```
- ## Self-Test
- Verify the server is working correctly:
- ```bash
- npm test
- # or
- css-mcp --self-test
- # or
- npx css-mcp --self-test
- ```
- Expected output:
- ```
- docs ok (simple slug): { input: 'grid', slug: '/en-US/docs/Web/CSS/grid', ... }
- docs ok (pseudo-selector + markdown): { input: ':has', ... }
- bcd ok: { bcd_id: 'css.properties.grid', has_compat: true, ... }
- ```
- ## 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
- ```bash
- # Clone the repository
- git clone https://github.com/stolinski/css-mcp.git
- cd css-mcp
- # Install dependencies
- npm install
- # Link for local development
- npm link
- # Run tests
- npm test
- ```
- ## 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:
- ```bash
- npm rebuild better-sqlite3
- ```
- ### Cache not working
- Check cache directory permissions:
- ```bash
- ls -la ~/.cache/css-mcp/
- ```
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.