Skip to content
Back to search

css-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stolinski--css-mcp/badge.svg)](/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)

  1. # CSS MCP Server
  2. An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN and comprehensive CSS code analysis.
  3. ## Features
  4. **Documentation & Compatibility:**
  5. - Official MDN Docs - Fetches documentation directly from MDN's API
  6. - Browser Compatibility - Includes browser support data from MDN's BCD
  7. - Simple API - Just pass CSS property names like `"grid"`, `"flexbox"`, or `":has"`
  8. - Markdown Conversion - Converts HTML documentation to clean, readable markdown
  9. - Auto-normalization - Supports both simple slugs (`"grid"`) and full paths (`"Web/CSS/grid"`)
  10. - Smart Caching - SQLite-based cache with 7-day TTL for blazing-fast responses
  11. **CSS Analysis:**
  12. - 150+ Metrics - Comprehensive analysis of stylesheet quality and complexity
  13. - Design Patterns - Detect color palettes, font sizes, spacing patterns
  14. - Code Quality - Selector complexity, specificity analysis, property usage
  15. - Performance Insights - Identify overly complex selectors and redundant code
  16. ## Installation
  17. ### For Claude Code
  18. Install via the Claude Code CLI:
  19. ```bash
  20. claude mcp add css -- npx -y css-mcp
  21. ```
  22. ### For VS Code
  23. One click install:
  24. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
  25. [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
  26. Install via VS Code CLI:
  27. ```bash
  28. code --add-mcp '{\"name\":\"css\",\"command\":\"npx\",\"args\":[\"-y\",\"css-mcp\"],\"env\":{}}'
  29. ```
  30. ### For MCP Clients (Claude Desktop, etc.)
  31. Add to your MCP settings configuration:
  32. ```json
  33. {
  34. "mcpServers": {
  35. "css": {
  36. "command": "npx",
  37. "args": ["-y", "css-mcp"]
  38. }
  39. }
  40. }
  41. ```
  42. ### For Development
  43. ```bash
  44. npm install -g css-mcp
  45. ```
  46. Or use with npx:
  47. ```bash
  48. npx css-mcp --self-test
  49. ```
  50. ## Requirements
  51. - Node.js 20+
  52. - Build tools for native modules (usually pre-installed on most systems)
  53. ## Usage
  54. ### Available Tools
  55. #### `get_docs`
  56. Fetch CSS documentation for any property, selector, function, or concept.
  57. **Parameters:**
  58. - `slug` (string) - CSS feature name or MDN path
  59. **Examples:**
  60. ```javascript
  61. // Simple slugs (auto-normalized)
  62. get_docs({ slug: "grid" });
  63. get_docs({ slug: ":has" });
  64. get_docs({ slug: "flexbox" });
  65. get_docs({ slug: "@media" });
  66. get_docs({ slug: "::before" });
  67. // Full MDN paths also work
  68. get_docs({ slug: "Web/CSS/grid" });
  69. get_docs({ slug: "en-US/docs/Web/CSS/border-radius" });
  70. ```
  71. **Returns:**
  72. ```json
  73. {
  74. "source": "mdn-doc",
  75. "slug": "/en-US/docs/Web/CSS/grid",
  76. "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/grid/index.json",
  77. "title": "grid",
  78. "mdn_url": "/en-US/docs/Web/CSS/grid",
  79. "summary": "The grid CSS property is a shorthand...",
  80. "body": [
  81. {
  82. "type": "prose",
  83. "title": "Syntax",
  84. "content": "The **`grid`** property is a shorthand..."
  85. }
  86. ]
  87. }
  88. ```
  89. #### `get_browser_compatibility`
  90. Fetch browser compatibility data for CSS features.
  91. **Parameters:**
  92. - `bcd_id` (string) - Browser Compat Data ID (e.g., `"css.properties.grid"`)
  93. **Example:**
  94. ```javascript
  95. get_browser_compatibility({ bcd_id: "css.properties.grid" });
  96. get_browser_compatibility({ bcd_id: "css.selectors.has" });
  97. ```
  98. #### `analyze_css`
  99. 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).
  100. **Parameters:**
  101. - `css` (string, required) - CSS code to analyze
  102. - `summaryOnly` (boolean, optional) - Return summary instead of full analysis. Default: `true`
  103. **Examples:**
  104. ```javascript
  105. // Summary mode (default, lightweight)
  106. analyze_css({
  107. css: `
  108. .container {
  109. display: grid;
  110. color: #3b82f6;
  111. }
  112. `
  113. });
  114. // Full analysis with all 150+ metrics
  115. analyze_css({
  116. css: "...",
  117. summaryOnly: false
  118. });
  119. ```
  120. **Returns (default summary):**
  121. ```json
  122. {
  123. "analysis": {
  124. "stylesheet": {
  125. "sourceLinesOfCode": 5,
  126. "size": 72
  127. },
  128. "rules": { "total": 1 },
  129. "selectors": {
  130. "total": 1,
  131. "averageComplexity": 1.0,
  132. "maxComplexity": 1
  133. },
  134. "colors": {
  135. "unique": 1,
  136. "uniqueColors": ["#3b82f6"]
  137. }
  138. },
  139. "note": "Summary metrics only. Use summaryOnly: false for complete 150+ metrics."
  140. }
  141. ```
  142. #### `analyze_project_css`
  143. 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.).
  144. Returns **curated summary metrics by default** (lightweight, ~1-2k tokens). Use `includeFullAnalysis: true` for complete data (uses ~10k+ tokens).
  145. **Automatically excludes:**
  146. - `**/node_modules/**`
  147. - `**/*.min.css`
  148. **Parameters:**
  149. - `path` (string, required) - File path, directory, or glob pattern
  150. - `includeFullAnalysis` (boolean, optional) - Return full 150+ metrics instead of summary. Default: `false`
  151. - `exclude` (array of strings, optional) - Additional glob patterns to exclude
  152. **Examples:**
  153. ```javascript
  154. // Analyze all CSS in a directory (summary - default, lightweight)
  155. analyze_project_css({ path: "dist" });
  156. // Full analysis with all 150+ metrics (uses more tokens)
  157. analyze_project_css({
  158. path: "dist",
  159. includeFullAnalysis: true
  160. });
  161. // Exclude additional patterns
  162. analyze_project_css({
  163. path: "dist",
  164. exclude: ["**/vendor/**", "**/*.legacy.css"]
  165. });
  166. // Analyze specific file
  167. analyze_project_css({ path: "public/styles.css" });
  168. // Use glob patterns
  169. analyze_project_css({ path: "dist/**/*.css" });
  170. ```
  171. **Returns (default summary):**
  172. ```json
  173. {
  174. "files": {
  175. "total": 5,
  176. "analyzed": 5,
  177. "errors": 0,
  178. "list": [
  179. { "path": "/path/to/style.css", "size": 2048 },
  180. { "path": "/path/to/theme.css", "size": 1024 }
  181. ]
  182. },
  183. "summary": {
  184. "stylesheet": {
  185. "sourceLinesOfCode": 450,
  186. "size": 12800
  187. },
  188. "rules": { "total": 85 },
  189. "selectors": {
  190. "total": 120,
  191. "averageComplexity": 1.4,
  192. "maxComplexity": 5
  193. },
  194. "colors": {
  195. "unique": 12,
  196. "uniqueColors": ["#3b82f6", "#10b981", ...]
  197. },
  198. "fontSizes": {
  199. "unique": 8,
  200. "uniqueSizes": ["1rem", "1.5rem", ...]
  201. }
  202. },
  203. "note": "Summary metrics only. Use includeFullAnalysis: true for complete data."
  204. }
  205. ```
  206. ## Cache Management
  207. The server automatically:
  208. - Creates cache at `~/.cache/css-mcp/cache.db`
  209. - Cleans up expired entries on startup
  210. - Tracks hit counts for each cached entry
  211. - Uses WAL mode for better concurrent performance
  212. To clear the cache:
  213. ```bash
  214. rm -rf ~/.cache/css-mcp/
  215. ```
  216. ## Self-Test
  217. Verify the server is working correctly:
  218. ```bash
  219. npm test
  220. # or
  221. css-mcp --self-test
  222. # or
  223. npx css-mcp --self-test
  224. ```
  225. Expected output:
  226. ```
  227. docs ok (simple slug): { input: 'grid', slug: '/en-US/docs/Web/CSS/grid', ... }
  228. docs ok (pseudo-selector + markdown): { input: ':has', ... }
  229. bcd ok: { bcd_id: 'css.properties.grid', has_compat: true, ... }
  230. ```
  231. ## Example: Using with Claude Code
  232. Once configured, you can ask Claude Code:
  233. **Documentation & Compatibility:**
  234. > "Use the CSS MCP to get documentation for flexbox"
  235. > "What browser support does :has selector have?"
  236. > "Explain how CSS grid works"
  237. **CSS Analysis:**
  238. > "Analyze this CSS and tell me what could be improved"
  239. > "What colors are used in my stylesheet?"
  240. > "Check the complexity of my selectors"
  241. **Project Analysis:**
  242. > "Analyze all CSS in my dist folder"
  243. > "What's the total complexity of my project's CSS?"
  244. > "Show me all colors used across my entire project"
  245. Claude will automatically use the MCP to fetch the latest MDN documentation and analyze CSS code.
  246. ## Development
  247. ```bash
  248. # Clone the repository
  249. git clone https://github.com/stolinski/css-mcp.git
  250. cd css-mcp
  251. # Install dependencies
  252. npm install
  253. # Link for local development
  254. npm link
  255. # Run tests
  256. npm test
  257. ```
  258. ## Performance & Limits
  259. **Caching:**
  260. - **First fetch**: ~400-500ms (network + cache write)
  261. - **Cached fetch**: ~100ms (**~5x faster**)
  262. - **Cache size**: ~390KB for typical usage
  263. **Input Limits:**
  264. - **Max file size**: 10MB per CSS file
  265. - **Max total size**: 50MB combined
  266. - **Max files**: 500 CSS files per analysis
  267. - **Network timeout**: 10 seconds for MDN API calls
  268. ## Troubleshooting
  269. ### "Module did not self-register"
  270. This usually means native modules need rebuilding:
  271. ```bash
  272. npm rebuild better-sqlite3
  273. ```
  274. ### Cache not working
  275. Check cache directory permissions:
  276. ```bash
  277. ls -la ~/.cache/css-mcp/
  278. ```
  279. Should show `cache.db`, `cache.db-shm`, and `cache.db-wal` files.
  280. ## Contributing
  281. 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 in

Free to use. If it’s helped, pass it on.