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" or "aurora gradient shaders" and Kroma resolves it live from the best design galleries, component libraries, 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.
• 7 specialized tools — inspiration, components, effects/shaders, site scraping, open web search, source discovery, and engineering-blueprint generation.

---

🔑 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

Tool	What it does
kroma_find_ui_inspiration	Searches live galleries (Mobbin, Godly, Awwwards, Dribbble, Lapa Ninja, Minimal Gallery, Land-book, Behance…) via Google Images for visual UI/UX inspiration.
kroma_find_component_code	Searches component libraries & docs (shadcn/ui, Magic UI, Aceternity, Uiverse, Tailwind, Radix, Headless UI, Flowbite, daisyUI, GitHub…) for copy-paste React / Vue / Svelte components.
kroma_find_effects_and_shaders	Discovers GLSL/canvas shaders, Framer Motion variants, GSAP scroll timelines, glassmorphism, glowing borders, Three.js and more from CodePen, Shadertoy, Codrops, GitHub, and blogs.
kroma_scrape_site_design	Scrapes any live URL and extracts layout, typography outline, fonts, color palette, and CSS/framework fingerprints (Tailwind, Radix, Framer, Next.js…).
kroma_search_design_web	General-purpose design/front-end web search, optionally scoped to specific domains. For anything the specialized tools don't cover.
kroma_list_sources	Lists the curated source registries so the agent can discover exact sources names. Runs offline — no API key needed.
kroma_generate_blueprint	Generates a full engineering blueprint (.md) for a larger project — overview, architecture, stack, data model, milestones, testing, plus optional live design/component/effect references. Returns the Markdown for you to save (stateless — writes no files).

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_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.

---

🖥️ 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_component_code",
        "kroma_find_effects_and_shaders",
        "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:

Path	Method	Purpose
/mcp	POST / GET / DELETE	Streamable HTTP transport (modern, recommended)
/sse	GET	Legacy SSE stream (Cursor / Windsurf compatibility)
/messages?sessionId=…	POST	SSE message channel
/health	GET	Liveness probe → { "ok": true }

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

Variable	Default	Description
SERPER_API_KEY	—	Required (unless passing api_key per call). Your Serper key.
SERPER_TIMEOUT_MS	20000	Per-request timeout in milliseconds.
KROMA_TRANSPORT	stdio	stdio or http.
PORT / KROMA_PORT	3000	HTTP port (http transport).
KROMA_HOST	0.0.0.0	HTTP bind host (http transport).

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-component-code.ts
    find-effects-and-shaders.ts
    scrape-site-design.ts
    search-design-web.ts
    list-sources.ts

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.

---

📄 License

MIT © 2026 Kroma MCP