design-library-mcp

A local, free, open-source design-reference library with two faces:

• a web gallery at http://127.0.0.1:8000 where you browse, search, preview and curate references, and

• an MCP server that Claude queries, so UI work starts from references you chose on purpose instead of generic defaults.

Everything runs on your machine. No API keys, no paid services, no cloud.

library/entries/*.json  ──►  library/index.db (SQLite + FTS5)   ──►  CLI · web gallery · MCP server
   source of truth             library/vectors.db (sqlite-vec)        one shared `core` package
                               rebuildable caches

Search is hybrid: keyword matching (FTS5) merged with semantic matching, so "spinner while waiting" finds a loader and "choose a plan" finds pricing tables even with no shared words. The meaning model (all-MiniLM-L6-v2) runs locally on your CPU.

1. Install (once)

Needs Python 3.11+ and uv (free, open source).

python -m pip install --user uv
cd "C:\path\to\design-library-mcp"
python -m uv sync            # creates .venv and installs everything (incl. semantic search)
python -m uv run python -m designlib rebuild   # builds the search index + meaning vectors
python -m uv run pytest -m "not slow"          # optional: tests, about 8 seconds

The first rebuild (or first search) downloads the meaning model once: about 90 MB from Hugging Face, free, no account. After that it works offline. Semantic search pulls in PyTorch (CPU build, a few hundred MB). To install without it: python -m uv sync --no-group semantic; search then uses keywords only and everything else works the same.

pip install --user puts uv in %APPDATA%\Python\Python3xx\Scripts, which usually isn't on your PATH, so this README writes python -m uv. Add that folder to PATH to type uv instead.

Related MCP server: DOM Inspector Plus MCP Server

2. Start the gallery

Double-click start.cmd, or in PowerShell:

cd "C:\path\to\design-library-mcp"
.\start.ps1

Both open http://127.0.0.1:8000 in your browser. Stop with Ctrl+C. If PowerShell says running scripts is disabled, use start.cmd, which doesn't need PowerShell.

The gallery only listens on 127.0.0.1, so other devices on your network cannot reach it.

You usually don't need to start it yourself: while Claude is open, the MCP server also serves the gallery, so the gallery_url links Claude gives you always open. If the gallery is already running (started by Claude or by you), start.cmd just opens it in your browser.

3. Connect Claude

The MCP server is started by Claude itself. You never run it by hand. Both setups below use the project's own Python (.venv\Scripts\python.exe), so they don't depend on PATH.

(a) Claude desktop app (Windows)

1. Open the config file. In the app: Settings → Developer → Edit Config, or open it directly: %APPDATA%\Claude\claude_desktop_config.json.

2. Add a design-library entry inside "mcpServers", next to any servers already there:

   {
     "mcpServers": {
       "design-library": {
         "command": "C:\\path\\to\\design-library-mcp\\.venv\\Scripts\\python.exe",
         "args": ["-m", "designlib", "mcp"]
       }
     }
   }

   Replace C:\\path\\to\\design-library-mcp with the folder you cloned the repo into. In JSON every backslash in a path is written twice (\\).

3. Quit Claude completely (system tray icon → Quit, not just closing the window) and reopen it.

4. In a new chat, open the tools/connectors menu: design-library should be listed with 6 tools.

(b) Claude Code

claude mcp add --scope user design-library -- "C:\path\to\design-library-mcp\.venv\Scripts\python.exe" -m designlib mcp

• --scope user makes it available in every project. Leave it out to add it only to the current project.

• Check it: claude mcp get design-library should say ✔ Connected. Inside Claude Code, /mcp lists it.

• Remove it: claude mcp remove design-library -s user

Make Claude use it every time (optional)

Claude reads the server's built-in instructions, but a line in your global ~/.claude/CLAUDE.md makes it a habit in Claude Code:

Before designing or building any UI, search the `design-library` MCP server
(search_designs, then get_design) and follow its style guide (list_styles / get_style_guide).
Say which references and style guide you used.

Things to ask Claude

• "Build a pricing section for my app. Check my design library first."

• "What toggles do I have saved? Show me the one I rated highest."

• "Use my quiet-product style guide to restyle this settings page."

• "Save https://example.com/some-landing-page to my design library as a screen, tagged hero, saas."

4. The MCP tools

gallery_url (http://127.0.0.1:8000/d/<id>) opens whenever Claude or start.cmd is running: the MCP server serves the gallery in the background if port 8000 is free. With several Claude sessions, the first one serves it; if that one closes, another takes over within 30 seconds. To turn this off, set the environment variable DESIGNLIB_GALLERY_WITH_MCP=0.

How semantic search behaves

• The gallery and the MCP server load the model in the background when they start (importing PyTorch takes ~10 s). Until then, searches use keywords only, so the gallery's live search never waits. Once ready, the result count says matched by meaning and keywords. Claude's searches wait for the model, so they always include meaning.

• Each entry's title, type, tags, notes, style notes and when to use / avoid are embedded. Code is left out on purpose (class names would drown the description).

• New or edited entries are embedded automatically before the next semantic search. Only entries whose text changed are re-embedded; toggling a favorite costs nothing.

• Results from both methods are merged with Reciprocal Rank Fusion: an entry found by both keywords and meaning ranks highest. Matches weaker than a cosine distance of 0.75 are dropped.

• Turn it off without uninstalling: set the environment variable DESIGNLIB_SEMANTIC=0.

5. Command line

python -m uv run python -m designlib <command>

add options: --title, --framework, --rating 1-5, --favorite, --no-fetch (don't contact the site).

6. Your library

About 10,000 references from 17 sources: full open-source component libraries (with code Claude Code can use or install directly) plus link-only inspiration galleries. The full list, licenses and how each was collected are in library/sources.md.

• Entries: library/entries/<id>.json, one file per reference. Edit them in the gallery (or by hand, then run rebuild). Commit them with git like any other file.

• Screenshots: uploaded in the gallery, stored in library/assets/mine/.

• Style guides: add library/styles/<name>.md. The first paragraph becomes the summary Claude sees in list_styles. Start from quiet-product.md.

• Sources: library/sources.md lists every source, its license, and whether code may be stored.

An entry has: id, title, source, url, license, type (style|component|screen|interaction|layout|palette|token), tags, framework (html|tailwind|react|none), style_notes {palette, fonts, spacing, mood}, notes, code, prompt, preview_image_url, local_image, when_to_use, avoid_when, my_rating (1-5), favorite, added_at, updated_at.

The rules it enforces

• Code is only stored for MIT, Apache-2.0, ISC or your own work (Own). The schema rejects anything else, whether it comes from the CLI, the gallery or Claude.

• Gallery and inspiration sites are link only: URL, title, tags, your notes, and the og:image URL (shown as a hotlink with no referrer). Their images and content are never downloaded.

• Fetching is polite: checks robots.txt, sends an honest User-Agent, waits 2 s between requests to the same site, reads at most 1 MB, and only reads metadata.

• Importers verify the repo's LICENSE file before reading anything, and stop if it isn't open.

No duplicates

Two entries count as the same resource when they have the same link and the same content (the same code, or the same preview image). Every import and add skips anything already in the library (add tells you which entry already has it), and designlib dedupe finds and merges older duplicates. Same link alone isn't a duplicate: a library's docs page can show several different examples, and one post can have several images.

Categories and platforms

Every reference is sorted two ways, like Collect UI's sidebar:

• Platform: Web, Mobile, Desktop, or Any platform (icons, colors, logos, and shots that don't say). Tabs at the top of the gallery.

• Category: what it is, in five groups (left sidebar):

  • Pages & sections: landing/home page, hero, navigation, footer, call to action, features, pricing, testimonials, FAQ, blog, about, contact, logo cloud, stats, newsletter, 404, ...

  • App screens: dashboard, login & sign up, onboarding, settings, profile, checkout, e-commerce, chat, inbox, calendar, tables, charts, empty states, search, AI interfaces, ...

  • Components: buttons, cards, forms, toggles, selects, modals, tooltips, tabs, accordions, alerts, badges, avatars, loaders, pagination, carousels, timelines, layouts, menus, ...

  • Motion & effects: animations, hover effects, text effects, scroll animations, backgrounds, 3D/WebGL

  • Style & brand: design styles, branding & logos, illustrations, typography, colors, icons, design tokens

An entry can be in up to three categories (best match first). Sorting is automatic: each tag and title word is looked up in core/taxonomy.py, web code counts as Web, and mobile-app / mac-app style tags decide Mobile / Desktop. When the rules can't tell, designlib categorize asks the local meaning model, but only accepts answers it was measured to get right 96%+ of the time; everything else stays Any platform.

To change a single entry, open it, choose Edit, and tick its categories and platform: your choice is kept from then on. To change the scheme, edit core/taxonomy.py and run python -m uv run python -m designlib categorize --force.

7. Project layout

design-library-mcp/
  start.cmd / start.ps1 / start.sh   start the gallery
  pyproject.toml, uv.lock            dependencies
  docs/testing.md                    tests + MCP Inspector walkthrough
  library/                           YOUR DATA (entries, assets, styles, sources.md)
  src/designlib/
    config.py                        paths, 127.0.0.1:8000
    cli.py                           the command line
    core/                            schema, storage, index, search, semantic, fetch, library, styleguide
    web/                             FastAPI app, Jinja templates, CSS/JS, vendored assets
    importers/                       hyperui.py, uiverse.py, common.py
    mcp_server.py                    the MCP tools
  tests/                             pytest suite

8. Troubleshooting

Credits and licenses

This project: MIT (see LICENSE). Third-party files stored in the project (src/designlib/web/static/vendor/), each with its license file: htmx 2.0.4 (0BSD), Tailwind CSS browser build 4.1.11 (MIT), highlight.js 11.10.0 (BSD-3-Clause), Familjen Grotesk font (SIL OFL 1.1). Semantic search uses sentence-transformers (Apache-2.0), sqlite-vec (MIT/Apache-2.0) and the all-MiniLM-L6-v2 model (Apache-2.0), downloaded at first use rather than stored in the repo. Imported components keep their source's license (HyperUI: MIT, Uiverse: MIT) and a link to the original file in each entry.