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.

• 6 specialized tools — inspiration, components, effects/shaders, site scraping, open web search, and source discovery.

Related MCP server: go_serper_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_scrape_site_design
{ "url": "https://linear.app", "include_markdown": true }

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

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"
      ]
    }
  }
}

🌐 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-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