Kroma MCP — @kromamcp/server

A completely stateless, internet-connected Model Context Protocol server for UI/UX design inspiration, live component discovery, and modern web micro-effects.

Kroma turns your AI assistant into a design scout. Ask for "a glassmorphic pricing card in React", "a grainy mesh gradient hero as CSS", "hand-drawn rocket icons", or "OG image inspiration for a dev tool" and Kroma resolves it live from the best design galleries, component libraries, gradient generators, icon sets, and code playgrounds on the internet — no local database, no cache, no stored files.

Every request is resolved in real time via the Serper API (Google Search / Images / Scrape).

✨ Highlights

• Completely stateless — zero databases, zero local caches, zero file storage. Every answer is fetched fresh.

• Real-time internet resolution — live queries against curated design galleries, component docs, and code repos.

• Multi-tenant & zero-config — connect and go. Keys resolve per-request from the environment or a tool argument.

• Two transports — stdio for desktop/IDE hosts, and Streamable HTTP + SSE for remote hosting.

• 10 specialized tools — UI inspiration, graphic & brand inspiration, components, effects/shaders, backgrounds & gradients, icons & logos, site scraping, open web search, source discovery, and engineering-blueprint generation.

• Smart source routing — every curated source is tagged, so asking for a mesh gradient as CSS or an OG image hits only the handful of sources that actually serve it.

Related MCP server: Design Inspiration MCP Server

🔑 Prerequisites

1. Node.js ≥ 18

2. A Serper API key — grab a free one at serper.dev (2,500 free credits to start).

Set it as an environment variable:

export SERPER_API_KEY="your_serper_key_here"

You can also pass a per-call api_key argument to any tool — it takes precedence over the env var. This is what makes Kroma multi-tenant: different callers can bring their own key.

🚀 Quickstart (npx)

No install required — run the latest published version directly:

SERPER_API_KEY=your_key npx -y @kromamcp/server

That starts the server on stdio, ready for any MCP host.

🧰 The Tools

Example tool arguments

// kroma_find_ui_inspiration
{ "query": "fintech dashboard dark mode", "sources": ["Mobbin", "Awwwards"], "num": 12 }

// kroma_find_component_code
{ "component": "command palette", "framework": "react", "keywords": "tailwind accessible" }

// kroma_find_effects_and_shaders
{ "effect": "animated glowing border", "category": "glow", "framework": "react" }

// kroma_find_graphic_inspiration
{ "query": "developer tool launch announcement", "asset": "social-post", "num": 12 }
{ "query": "seed round pitch deck", "asset": "deck" }
{ "query": "dark OG image with product screenshot", "asset": "og-image" }

// kroma_find_backgrounds_and_gradients
{ "look": "dark purple hero backdrop", "style": "mesh", "format": "css" }
{ "look": "warm grainy noise texture", "style": "grainy", "include_previews": true }
{ "look": "accessible brand color ramp", "style": "palette", "format": "code" }

// kroma_find_icons_and_logos
{ "query": "rocket deploy", "kind": "icon", "style": "hand-drawn", "free_only": true }
{ "query": "minimal fintech symbol", "kind": "logo" }

// kroma_scrape_site_design
{ "url": "https://linear.app", "include_markdown": true }

// kroma_search_design_web
{ "query": "design tokens naming conventions", "sites": ["web.dev", "smashingmagazine.com"] }

// kroma_generate_blueprint
{ "project": "Fintech onboarding dashboard", "kind": "dashboard", "stack": ["Next.js", "TypeScript", "Postgres"], "goals": ["Reduce drop-off", "SOC2-ready"], "depth": "deep" }

Every tool returns both a readable JSON text block and structuredContent. Errors come back as graceful isError results (with an auth / request / unknown kind) instead of crashing the session.

Honest results

Google silently drops the site: operator when the scoped domains have a thin search index — and several of the best galleries (Deck.gallery, OGFolio, Footer.design, Ramps) are recent single-page apps with almost nothing indexed. So the three routing tools tell you exactly what you got:

generators / galleries / libraries always carry the matched sources with direct URLs. For a single-page generator like ColorFlow or Pryzm, that URL is the answer — there's no article to find.

🖥️ Client Setup

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kroma": {
      "command": "npx",
      "args": ["-y", "@kromamcp/server"],
      "env": {
        "SERPER_API_KEY": "your_serper_key_here"
      }
    }
  }
}

Restart Claude Desktop. You'll see the Kroma tools appear under the tools menu.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "kroma": {
      "command": "npx",
      "args": ["-y", "@kromamcp/server"],
      "env": { "SERPER_API_KEY": "your_serper_key_here" }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kroma": {
      "command": "npx",
      "args": ["-y", "@kromamcp/server"],
      "env": { "SERPER_API_KEY": "your_serper_key_here" }
    }
  }
}

Roo Code

In the Roo Code MCP settings (mcp_settings.json), add:

{
  "mcpServers": {
    "kroma": {
      "command": "npx",
      "args": ["-y", "@kromamcp/server"],
      "env": { "SERPER_API_KEY": "your_serper_key_here" },
      "alwaysAllow": [
        "kroma_find_ui_inspiration",
        "kroma_find_graphic_inspiration",
        "kroma_find_component_code",
        "kroma_find_effects_and_shaders",
        "kroma_find_backgrounds_and_gradients",
        "kroma_find_icons_and_logos",
        "kroma_scrape_site_design",
        "kroma_search_design_web",
        "kroma_list_sources",
        "kroma_generate_blueprint"
      ]
    }
  }
}

🌐 Remote Hosting (HTTP + SSE)

For a shared, always-on deployment, run Kroma over HTTP:

SERPER_API_KEY=your_key npx -y @kromamcp/server --transport http --port 3000
# or: KROMA_TRANSPORT=http PORT=3000 npx -y @kromamcp/server

This exposes:

Connecting a client to the SSE endpoint

Hosts that support a URL/SSE endpoint (e.g. Cursor, Windsurf) can point at:

{
  "mcpServers": {
    "kroma": {
      "url": "https://your-host.example.com/sse"
    }
  }
}

Or the Streamable HTTP endpoint:

{
  "mcpServers": {
    "kroma": {
      "url": "https://your-host.example.com/mcp"
    }
  }
}

When self-hosting, provide SERPER_API_KEY in the server's environment, or have each caller pass an api_key tool argument for true multi-tenant, bring-your-own-key operation.

⚙️ Configuration

CLI flags: --transport <stdio|http>, --http, --port <n>, --host <h>, --help, --version.

🛠️ Local Development

git clone <this-repo>
cd kroma-mcp
npm install
npm run build        # compile TypeScript → dist/
npm start            # run the compiled server (stdio)
npm run dev          # tsc --watch
npm run typecheck    # type-check without emitting

Project layout

src/
  index.ts                 # entry point + stdio/http transports
  services/serper.ts       # stateless Serper API gateway (search/images/scrape)
  lib/
    sources.ts             # curated source registries + query builders
    response.ts            # MCP result helpers + error guard
  tools/
    find-ui-inspiration.ts
    find-graphic-inspiration.ts
    find-component-code.ts
    find-effects-and-shaders.ts
    find-backgrounds-and-gradients.ts
    find-icons-and-logos.ts
    scrape-site-design.ts
    search-design-web.ts
    list-sources.ts
    generate-blueprint.ts

Adding a source

Every source is a CuratedSource in src/lib/sources.ts:

{
  name: "Grainient",
  domain: "grainient.supply",
  note: "1,000+ grainy, smooth, and animated gradients plus AI backgrounds and a shader tool",
  tags: ["grainy", "animated", "mesh", "ai", "shader", "image"],
}

Drop it into the right registry (INSPIRATION_SOURCES, COMPONENT_SOURCES, EFFECT_SOURCES, GRAPHIC_SOURCES, BACKGROUND_SOURCES, ICON_SOURCES) and it's live — kroma_list_sources reads the arrays directly and the search tools build site: queries from them. name is what callers pass in sources; tags are what the asset / style / format / kind filters match against.

Architecture principles

• Stateless by construction. No module holds user data between requests; HTTP sessions live only in-memory for the process lifetime and store no personal data.

• Dynamic key resolution. resolveApiKey(explicit?) prefers an explicit api_key argument, then SERPER_API_KEY. Nothing is persisted.

• Graceful failure. Network errors, timeouts, and auth failures become typed, readable tool errors — never uncaught throws.

• Widening fallbacks. Source filters never return an empty set: an unrecognised name or an over-narrow tag combination widens back to the parent registry, so a bad argument degrades into a broader search instead of zero results.

📄 License

MIT © 2026 Kroma MCP