Submit
stolinski

CSS MCP Server

Community stolinski
Updated

CSS MCP Server

An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN, with intelligent caching.

Features

Simple API - Just pass CSS property names like "grid", "flexbox", or ":has"Official MDN Docs - Fetches documentation directly from MDN's APIMarkdown Conversion - Converts HTML documentation to clean, readable markdownSmart Caching - SQLite-based cache with 7-day TTL for blazing-fast responsesAuto-normalization - Supports both simple slugs ("grid") and full paths ("Web/CSS/grid")Browser Compatibility - Includes browser support data from MDN's BCD

Installation

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

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:

// 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:

{
  "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:

get_browser_compatibility({ bcd_id: "css.properties.grid" });
get_browser_compatibility({ bcd_id: "css.selectors.has" });

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:

rm -rf ~/.cache/css-mcp/

Self-Test

Verify the server is working correctly:

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:

"Use the CSS MCP to get documentation for flexbox"

"What browser support does :has selector have?"

"Explain how CSS grid works"

Claude will automatically use the MCP to fetch the latest MDN documentation.

Development

# 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

With caching enabled:

  • First fetch: ~400-500ms (network + cache write)
  • Cached fetch: ~100ms (~5x faster)
  • Cache size: ~390KB for typical usage

Troubleshooting

"Module did not self-register"

This usually means native modules need rebuilding:

npm rebuild better-sqlite3

Cache not working

Check cache directory permissions:

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

MCP Server · Populars

MCP Server · New