qloo-mcp

An MCP server that gives any AI agent the Qloo Taste AI graph as tools, plus Taste Match, an agent that tells an independent artist exactly who would love a piece from their catalog.

Built for the Qloo Agentic Hackathon: https://qloo.devpost.com/

Why

Independent artists sell to "people who like this kind of thing" and have no way to say who those people are. A generic LLM can guess. Qloo knows: its taste graph links 250M+ artists, films, books, brands and places to real affinity data, demographics and locations. Taste Match turns one description of a print or a song into:

• the artists, films, books and brands its audience already loves

• the places in a chosen city where those people go (galleries, cafes, shops, venues)

• the age and gender affinity of that audience

• the words that describe that taste

• a ready-to-use plain-text pitch

Related MCP server: Booker

Tools

Every tool validates input with Pydantic and returns JSON. Failures come back as structured errors (invalid_input, missing_api_key, qloo_api_error, unknown_tool), never tracebacks.

How Taste Match works

1. Plan. The artist gives a title, a description, and optionally influences and style keywords. If an OpenAI-compatible LLM is configured (TASTE_MATCH_LLM_URL), the agent asks it for more influences and keywords. Without one, a deterministic keyword extractor fills in. Artist-supplied seeds always win.

2. Resolve. Every seed is looked up in Qloo in parallel (/search for entities, /v2/tags for tags) to get real Qloo IDs.

3. Fan out. Seven parallel Qloo insight calls: artists, places (restricted to the chosen city), brands, books, movies, demographics, taste tags.

4. Synthesize. Seeds are removed from results, demographics are averaged into an audience profile, and a plain-text pitch is written from the top matches.

One failing branch becomes a note in the result instead of failing the whole match.

Install

Requires Python 3.11+.

git clone https://github.com/NoBanks/qloo-mcp
cd qloo-mcp
python3.11 -m pip install -e .

Configuration

The key is sent only as the X-Api-Key header and is never logged.

Claude Desktop / any MCP client

{
  "mcpServers": {
    "qloo": {
      "command": "qloo-mcp"
    }
  }
}

Add QLOO_API_KEY to the environment the client launches the server with (in Claude Desktop, an env object inside the qloo entry).

Hackathon demo

The demo is a small web app plus a CLI, both driving the same taste_match agent the MCP tool uses.

Web app (the hosted demo)

python3.11 -m pip install -e ".[demo]"
export QLOO_API_KEY=...        # your key
uvicorn demo.web_app:app --host 0.0.0.0 --port 8080

Open http://localhost:8080, pick an example work (or describe your own), and press Find my audience.

Routes: GET / (UI), GET /api/catalog (example works), POST /api/match (runs Taste Match), GET /healthz. POST /api/match is rate limited per IP (TASTE_MATCH_RATE_PER_MIN, default 10).

Deploy anywhere that runs a container. The included Dockerfile serves the app on $PORT:

docker build -t taste-match .
docker run -p 8080:8080 -e QLOO_API_KEY=... taste-match

CLI agent

export QLOO_API_KEY=...
python3.11 demo/taste_match_agent.py              # every work in demo/catalog.json
python3.11 demo/taste_match_agent.py --index 2    # one work
python3.11 demo/taste_match_agent.py --title "Neon Koi" --kind artwork \
  --description "Glowing koi in a night pond, ukiyo-e meets cyberpunk" \
  --influences "Hokusai,Blade Runner" --location "Seattle"

Add --json for the raw result.

Tests

python3.11 -m pip install -e ".[dev,demo]"
python3.11 -m pytest tests/ -v

All HTTP is mocked with respx. No key or network is needed to run the suite.

License

MIT. See LICENSE.

Built by Ryan Hammer (NoBanks): https://github.com/NoBanks