Refero MCP
OfficialRefero MCP lets you search, browse, inspect, and turn Refero design styles into agent-ready DESIGN.md files, subject to Refero's current block on live catalog access.
Natural-language search the style catalog with query, optional theme filter, tag-style filters, and result limit.
Fetch a full design system for a style by UUID, hostname/URL, or fuzzy-matched site name.
Render a style as DESIGN.md and optionally write it to
<vault>/05-Projects/<project>/DESIGN.md.Get Refero's similar-style recommendations for a style.
Browse the local catalog mirror with pagination, theme filters, and tag filters.
Force a full catalog re-fetch/refresh, though live-data-dependent tools may fail while the upstream endpoint is blocked.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Refero MCP Find a dark editorial style with a serif font."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Refero MCP
Search styles.refero.design in plain English and drop a DESIGN.md into any project.
Quick Navigation
Link | Section | What it does | Time |
Read first | Refero blocks this client today | ~1 min | |
Overview | The catalog, the gap, the wrap | ~1 min | |
Setup | One line into Claude Code | ~1 min | |
Talk to it | Plain-English prompts | ~2 min | |
Reference | The six tools, one line each | ~1 min | |
Setup | Env vars + JSON config | ~1 min | |
Reference | Cache, embeddings, DESIGN.md generation | ~1 min | |
Reference | The likely first three problems | ~1 min | |
Meta | MIT | — |
Related MCP server: mcp-library-docs
Status: Refero is refusing this client
New installs can't search right now. As of 2026-11-01, GET styles.refero.design/api/styles answers this package with HTTP 403 and {"error":"Please refresh the page and try again."}. The last successful catalog fetch I have on record is 2026-08-04.
What that means in practice:
If you have... | What works |
No local cache | Nothing. Every tool returns a clear error saying why. |
A cached catalog |
|
A cached style |
|
Either |
|
This package always read an undocumented endpoint, and it won't try to get around the block. Refero's robots.txt disallows /api/, and its Terms of Use (updated August 3, 2026) rule out automated extraction outside documented features and bypassing access controls.
For live data, use Refero's official MCP. It covers style search and full style guidance (colors, typography, spacing, do/don't rules), plus sites, apps, screens, and flows. It requires a paid Refero plan (Pro, Team, or Lifetime):
claude mcp add --transport http refero https://api.refero.design/mcp --header "Authorization: Bearer <token>"To check whether this section is still true, run REFERO_LIVE_TEST=1 npx vitest run tests/live.test.ts. It sends one request to the real endpoint and fails if the state has changed, in either direction. Because robots.txt disallows that path, the test is manual only: it's skipped by default and never runs in CI, so CI won't notice if the state changes.
What this is
Refero Styles is a beta catalog of about 200 curated sites where someone has done the painful work of pulling out the colors, typography, spacing, and per-style do/don't guidance. Each entry ships with a designSystem block that's basically a DESIGN.md waiting to happen.
This MCP wraps that catalog so Claude Code can search it in natural language and drop a generated DESIGN.md straight into whatever project you're scaffolding. No browser-tab JSON copy-paste, no hand-rolled token tables.
It's for anyone using Claude Code to spin up a new app, deck, or client project who wants the design language locked down before the first component renders.
Quick install
One line:
claude mcp add refero -- npx -y fidgetcoding-refero-mcpRestart Claude Code and start describing the look you want.
If you want vibe search (semantic ranking against each style's poetic northStar summary), pass an OpenAI key:
claude mcp add refero --env OPENAI_API_KEY=sk-... -- npx -y fidgetcoding-refero-mcpWithout it, search falls back to keyword scoring. Works fine, just less magical.
For claude_desktop_config.json users:
{
"mcpServers": {
"refero": {
"command": "npx",
"args": ["-y", "fidgetcoding-refero-mcp"],
"env": {
"OPENAI_API_KEY": "sk-...",
"REFERO_MCP_VAULT_DIR": "/absolute/path/to/your/vault"
}
}
}
}Usage
You talk. Claude dispatches. No commands, no syntax, no JSON.
Every tool here is wired to plain-English prompts. You don't memorize tool names or build payloads — Claude picks the tool and fills in the parameters.
A few prompts that route cleanly:
"Find me a dark editorial style with a serif and a warm accent.""Pull the full breakdown for Linear.""What's similar to Vercel in the Refero catalog?""Render Cursor's DESIGN.md — don't save it yet, just show me.""Save Cursor's DESIGN.md into my ACME project.""Show me only dark-mode brutalist styles, top five.""Refresh the Refero catalog before we start the design pass."More worked recipes in docs/USAGE.md.
Tools
Tool | What it does |
| Natural-language vibe search across the catalog. Embeddings if |
| Fetch the full design system for one style. Accepts a uuid, hostname (e.g. |
| Refero's own "similar styles" ranking for a given style. Free recommendations from the upstream. |
| Browse the local catalog mirror with optional theme/tag filters. Stably ordered. |
| What's actually in the catalog — ranked font stacks, color names, theme counts. Call it before guessing search terms: there is no tag taxonomy, so invented tags match nothing, but every value this returns is already in the search index and can be passed straight to |
| Render a style as an agent-friendly DESIGN.md (frontmatter, north star, color table, dos/donts). Optionally writes to disk. |
| Force a full re-fetch of the catalog and overwrite the local mirror. Skips the 24h TTL. |
Configuration
Everything is optional. Defaults are picked so the MCP just runs.
Variable | Required | Default | What it does |
| No | unset | Enables vibe search via |
| No |
| Override if Refero ever moves the API or you're pointing at a fixture. |
| No |
| Where the local catalog mirror, embeddings, and detail cache live. |
| No |
| How long a cached page is considered fresh. |
| No (required for project writes) | unset | Absolute path to the vault root that |
A copy-paste .env.example ships in the repo root.
There's no default for
REFERO_MCP_VAULT_DIR. The previous draft hardcoded my laptop path, which worked great for exactly one machine on Earth. The reviewer caught it. Now if you don't set it, the tool just refuses to write — rude, but better than dropping files into a folder that doesn't exist on your computer.
How it works
This describes the design, which depends on an endpoint Refero now refuses (see Status). That endpoint was never publicly documented: the shape was mapped empirically against the live site, and the breakdown is in docs/api-surface.md.
Local catalog mirror. Refero exposes
?page=Npagination but silently ignores?search=,?q=, and?colorScheme=. So this MCP walks the pages once, mirrors them locally underREFERO_CACHE_DIR, and runs all filtering and ranking client-side.Vibe search via
northStar. Every Refero style ships with a one-line poetic summary callednorthStar. WithOPENAI_API_KEYset, the MCP embeds those summaries withtext-embedding-3-smalland ranks by cosine similarity to your query. Without a key, it falls back to keyword scoring onnorthStar+ tags + site name.DESIGN.md generated locally. Refero does not expose a
/design.mdendpoint. The MCP synthesizes one fromstyle.fullResult.designSystem(dos, donts, tags, theme, role-tagged colors). Output is compatible with the/stitch-design-tasteand/design-taste-frontendskills.
Troubleshooting
"The Refero catalog is unavailable and there is no local copy." Refero is refusing this client and you have no cache to fall back on. See Status. Refreshing won't help.
Results say "Cached, may be stale". The live refresh failed, so you're getting your last good copy. The note gives its date and the reason.
Search results feel keyword-y rather than semantic. You probably don't have OPENAI_API_KEY set. Add it to your MCP config and restart, or lean harder on the catalog's vocabulary (industries plus tags like editorial, brutalist, glass).
refero_design_md returns markdown but won't write to disk. REFERO_MCP_VAULT_DIR is unset. Set it to your vault root (absolute path) and the tool will write to <vault>/05-Projects/<NAME>/DESIGN.md. Without it, you get the markdown back in conversation and can paste it wherever.
License
MIT — see LICENSE for details.
Author
Built by Nate Davidovich / Lorecraft LLC.
GitHub: lorecraft-io
npm: lorecraft
Sister projects: morgen-mcp, motion-mcp
Security: gitleaks scan
This repo ships with a .gitleaks.toml config and a scripts/security-scan.sh
helper that scans the working tree for secrets (GitHub tokens, API keys, JWTs,
private keys, Anthropic keys, etc.).
bash scripts/security-scan.shA .husky/pre-commit hook also runs gitleaks protect --staged on every commit
and warn-no-ops if gitleaks isn't installed locally.
If you don't have it yet:
macOS:
brew install gitleaks
Available Tools
6 toolsrefero_design_mdA
Render a Refero style as an agent-friendly DESIGN.md (frontmatter, north star, color table, fonts, dos/donts, tags). When save_to_project is set, writes the file to /05-Projects//DESIGN.md.
Inputs: identifier (required), save_to_project.
refero_getA
Fetch the full design system for a single style. Accepts a uuid, a hostname/URL (e.g. cursor.com), or a site name (e.g. "Cursor"). Fuzzy-matches site names within Levenshtein distance 2.
Inputs: identifier (required).
refero_listA
Browse the local catalog mirror with optional theme/tag filters. Returns paginated, stably-ordered results (newest first, then site name).
Inputs: theme, tags, page, limit.
refero_refreshA
Force a full re-fetch of the styles.refero.design catalog and overwrite the local mirror. Useful after the catalog has changed and you don't want to wait for the 24h TTL.
Inputs: no named parameters.
refero_searchA
Natural-language search over the styles.refero.design catalog. Returns the top matches scored by an embedding model (when OPENAI_API_KEY is set) or a BM25-lite keyword fallback. The local catalog is mirrored on first call and refreshed automatically every 24 hours.
Inputs: query (required), theme, tags, limit.
refero_similarA
Refero's own "similar styles" recommendation list for a given style. Useful for follow-up exploration once you've found a candidate via refero_search.
Inputs: identifier (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: fetching details, browsing, searching, refreshing, getting recommendations, and generating design docs. No overlap in functionality.
All tools share the 'refero_' prefix and use lowercase with underscores, but the suffixes vary between verbs (get, list, refresh, search) and non-verbs (similar, design_md), causing slight inconsistency.
6 tools is well-scoped for interacting with a design system catalog, covering key operations without being too few or too many.
The tool set covers browsing, searching, fetching details, getting recommendations, refreshing the catalog, and generating documentation. Minor gaps like filtering by popularity are absent but core workflows are complete.
Maintenance
Related MCP Connectors
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Search, organize, generate design guidance from, and reconstruct what you save in Hipppo.
Serves your design system and coding standards to coding agents, so they stop guessing.
Search and read Apple developer documentation, HIG, and WWDC transcripts as Markdown.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides resources, tools, and prompts for a Design System via MCP protocol, enabling component search, reading, and related component discovery.ISC
- AlicenseAqualityBmaintenanceProvides AI assistants with access to design documentation across multiple code libraries, enabling discovery of existing utilities and patterns to avoid reimplementation.32MIT
- AlicenseNot gradedqualityDmaintenanceAnalyzes codebases to automatically generate README, API docs, architecture diagrams, and CHANGELOG.6 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables intent-based semantic search over external design system documentation, allowing MCP-compatible AI assistants to retrieve relevant design tokens, component architectures, and code patterns via a single tool.-