Skip to main content
LoopHaven

A local-first API, CLI and MCP server for Looperman.

Search loops and acapella previews with real filters, get clean JSON, and pull the file you picked — from your terminal or from an AI agent.

PyPI Python tests FastAPI MCP License

LoopHaven — an unofficial Looperman API, CLI and MCP server

Looperman has no public API. LoopHaven is a local-first wrapper around the site: a FastAPI service, a haven CLI and an MCP server that expose its real search filters as clean JSON, so you can find loops and acapella previews and pull the file you picked — from Python, from your terminal, or from an AI agent.

It is not affiliated with Looperman. Downloads use your own account and its quota, at human pace; nothing here redistributes audio or works around a limit.

Why this exists

Looperman hosts a huge community sample library and has no public API. Every "scraper" out there stops at "here is some HTML". LoopHaven does three things differently:

  1. It speaks the site's own filter vocabulary. Genre, category, key, time signature, tempo range, date window, sort order — resolved from the real advanced-search form, not guessed from URL slugs. Ask for F#m, Bb or 4/4 and it maps them to what the site actually submits.
  2. It is honest about what it returns. total is null past page 1, because Looperman stops counting. When the quota is hit you get a 429, not a silent MP3 renamed to .wav.
  3. It plugs into a DAW workflow and into agents. One HTTP API, a haven CLI, and an optional MCP server so Claude, Cursor or any MCP client can search and fetch material on your behalf.

Looperman

Built on top of Looperman

Unofficial · not affiliated with or endorsed by Looperman Ltd.
The name and logo are trademarks of their owner, used only to identify the site this tool reads.

Unofficial project. LoopHaven is not affiliated with, endorsed by, or supported by Looperman. It reads public pages and your own session, at human pace. It does not redistribute audio and does not bypass quotas. Read DISCLAIMER.md before using it.


Quickstart

pip install "loophaven[mcp]"

# 1. start the local API
python -m uvicorn loophaven.api.app:app --host 127.0.0.1 --port 8000

# 2. search (public previews need no account)
curl "http://127.0.0.1:8000/api/search?genre=Trap&bpm=140&limit=2"

Working on the code instead? git clone https://github.com/mohamed-amine-ben-mallessa/loop-haven.git, then python -m pip install -e ".[dev,mcp]" — nothing else changes.

A real response, trimmed:

{
  "success": true,
  "count": 2,
  "looperman_url": "https://www.looperman.com/loops?gid=54&ftempo=140&ttempo=140&order=date&dir=d",
  "resolved": { "genre": { "id": 54, "label": "Trap" } },
  "loops": [
    {
      "id": "436799",
      "title": "Lil Uzi Vert Arp Type Loop",
      "bpm": 140,
      "genre": "Trap",
      "key": "Cm",
      "author": "NiemiroMTS",
      "duration_seconds": 13,
      "mp3_url": "https://www.looperman.com/media/loops/8513679/looperman-l-8513679-0436799-...mp3",
      "url": "https://www.looperman.com/loops/detail/436799/..."
    }
  ]
}

Interactive docs are at http://127.0.0.1:8000/docs.

CLI

The CLI talks to the local API, so start the server first.

# find material
haven search --genre Trap --bpm 140 --key Cm --limit 4
haven search --kind acapellas --genre "Boom Bap" --bpm 86 --mf 1 --json

# check what a download will give you (free: does not spend quota)
curl "http://127.0.0.1:8000/api/download/info/loop/436799"

# log in with your own account, then download (WAV for loops, MP3 for acapellas)
haven login
haven download --id 436799                 # saves under the upstream filename
haven download --id 24926 --kind acapella --out vocals.mp3

# audition a preview, toggle a favourite
haven play --id 436799
haven fav --hash <favorite_hash> --type loop

haven download asks /api/download/info first and prints the format, size and availability before spending anything. It exits 2 with a reason when there is no session or the quota is spent, and it never retries a 429.

haven login prompts locally and never stores your password. The session cookie is persisted so a server restart does not log you out.

API

Method Route What it does
GET /api/health status + whether a session is open
GET /api/filters full vocabularies (genres, categories, keys, sorts…)
GET /api/search loop search with real filters
GET /api/acapellas/search acapella search + licence wording
GET /api/loop/{id} one loop, parsed from JSON-LD
GET /api/acapellas/{id} one acapella + usage terms
GET /api/download/info/{kind}/{id} what you would get, without spending quota
GET /api/download/audio/{kind}/{id} the actual file
POST /api/download/zip personal ZIP of 2–4 loops
POST /api/auth/login open a Looperman session
GET /api/auth/status session state (never the email)
POST /api/favorites/toggle toggle a favourite (needs login)
GET /api/stream/preview stream a public MP3 preview
GET /api/download/proxy same-origin proxy for previews

Full parameter reference: docs/API.md · Filter tables: docs/FILTERS.md · How the site's internals were mapped: docs/REVERSE-ENGINEERING.md.

Documentation site (same content, one page per question): https://mohamed-amine-ben-mallessa.github.io/loop-haven/ — including the Looperman API question, the filter reference and the two download limits.

MCP

{
  "mcpServers": {
    "loophaven": {
      "command": "loophaven-mcp",
      "env": { "LOOPHAVEN_API": "http://127.0.0.1:8000" }
    }
  }
}

Tools: search_loops, search_acapellas, get_acapella_detail, get_preview_url, export_loop_zip, toggle_favorite. The agent sees JSON, never HTML.

There is also a ready-made skill in skills/loop-haven/SKILL.md that teaches an agent the etiquette: preview before download, respect the licence label, never bulk-scrape.

How the filters work

Looperman's advanced search posts a form; the ids below are the real ones, read from the form itself.

Filter Parameter Example
Genre genre → gid Trap (54), Hip Hop (7), Phonk (70)
Category category → cid Piano (21), Drum (1), Vocal (6)
Key key → mkey Am, F#m → fsm, Bb → am
Tempo bpm or ftempo/ttempo bpm=140 → exact; ftempo=90&ttempo=110
Time signature tsig 4/4 → 4x4
Date window when 1=24 h, 2=7 d, 3=30 d, 4=60 d
Sort order + dir downloads/d, date/d
Keywords keyword → keys +funky -techno

Labels, ids and slugs are all accepted; unknown values return 422 with suggestions instead of an empty result page. Call /api/filters for the whole vocabulary — 69 genres, 40 categories, 24 keys.

Honest limitations

  • This is a wrapper, not an API. If Looperman changes its HTML, parsing breaks. That is the whole reason the reverse-engineering notes are in the repo. Three standalone write-ups cover the parts that cost the most time: the hidden search form, the DOM traps and checking a session honestly.
  • total is null after page 1. Looperman caps the displayed count at 5,000 and stops showing it on later pages. LoopHaven reports that instead of inventing a number.
  • Downloads need your account and are quota-limited. One account per person. A 429 means wait, not retry harder. Nothing here is designed to evade it.
  • Acapellas have no WAV. Wherever the site serves MP3, the API says MP3 in Content-Type and a .mp3 filename.
  • The browser UI at / is a French prototype. The API, CLI and docs are in English; that page has not been translated yet.
  • Local single-user only. There is no API authentication. Do not expose it to the internet as-is.

LoopHaven is MIT-licensed code. The loops and acapellas it helps you find are not covered by that licence: they belong to their creators and are offered under Looperman's terms. Looperman is a trademark of its owner. This project is independent and unaffiliated.

What the project does, on purpose:

  • one query at a time, like a browser, with pauses;
  • no bulk harvesting, no mirroring of the catalogue;
  • no re-hosting of audio — the repo ships zero .mp3/.wav;
  • quotas and account limits are respected, never worked around.

If you are from Looperman and want something changed, open an issue — it will be handled quickly. See DISCLAIMER.md.

Contributing

Bug reports, parser fixtures and doc translations are the most useful things right now. See CONTRIBUTING.md and the good first issues.

python -m pip install -e ".[dev]"
python -m pytest tests/unit -q

Licence

MIT — take it, fork it, ship it. A star keeps the crate warm.

Metadata

Release files for loophaven 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for loophaven 0.2.0
File Size Uploaded Provenance Actions
loophaven-0.2.0.tar.gz 44.5 kB Without provenance Details for loophaven-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for loophaven 0.2.0
File Interpreter ABI Platform Actions
loophaven-0.2.0-py3-none-any.whl Python 3 none any Details for loophaven-0.2.0-py3-none-any.whl

Total release size: 86.7 kB

Release files / loophaven-0.2.0.tar.gz

Download URL loophaven-0.2.0.tar.gz
Size 44.5 kB
Tags Source
SHA-256 checksum
How to use checksums
609c1ac1eabc7c776ccea2e76518388b400733c9566ba212a08d8b32efe3f6a0
BLAKE2b-256 checksum
How to use checksums
ba8a343091e2a64fe8fbe81ea9314d6f81f14ccf3e0419250af8666efc704d29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / loophaven-0.2.0-py3-none-any.whl

Download URL loophaven-0.2.0-py3-none-any.whl
Size 42.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9baf2da99fda102c014d15e78437a451d9657988aabd07f92baf73861c042fb1
BLAKE2b-256 checksum
How to use checksums
b77a1b76f1f572de9c2a248b8582f81ab9ffe8bd4cdd3510df9ba4fc1c1305d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for loophaven 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page