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.
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:
- 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,Bbor4/4and it maps them to what the site actually submits. - It is honest about what it returns.
totalisnullpast page 1, because Looperman stops counting. When the quota is hit you get a429, not a silent MP3 renamed to.wav. - It plugs into a DAW workflow and into agents. One HTTP API, a
havenCLI, and an optional MCP server so Claude, Cursor or any MCP client can search and fetch material on your behalf.
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.
totalisnullafter 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
429means 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-Typeand a.mp3filename. - 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.
Legal
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.