Content
# 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
Connection Info
You Might Also Like
No recommendations available