discogs-mcp
Provides tools for accessing Discogs database, collection, wantlist, and marketplace data. Supports searching releases, masters, artists, and labels; reading and managing collection and wantlist items with dry-run write safety; fetching marketplace prices and collection value; syncing a local SQLite cache for SQL analysis and summaries; and optional local-library matching against Discogs releases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@discogs-mcp Sync my Discogs collection, then tell me which labels I own the most of."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
discogs-mcp
An MCP server that gives Claude full access to Discogs: database lookups, your collection and wantlist (read and write), marketplace prices, and a local SQLite cache so Claude can analyse the whole collection without paging through the API.
Database: search; releases, masters and their versions; artists; labels.
Collection and wantlist: read, add, move, rate, set fields, remove. Every write is a dry run until you confirm it.
Marketplace: lowest price and number for sale, suggested prices by condition, and collection value.
Local cache:
sync_collectiononce, then use read-only SQL (query_collection) andcollection_summary.Digital library matching (optional): scan your audio files' tags, match the albums to Discogs releases, and find gaps between your vinyl and your digital copies. It never writes tags.
Runs over stdio for Claude Desktop, or over streamable HTTP with bearer auth.
Setup
Install uv and clone the repo:
git clone https://github.com/hlights33/discogs-mcp.git cd discogs-mcp uv sync # add --extra local for the digital-library toolsGet a Discogs token. On discogs.com, go to Settings → Developers → Generate new token. This is a personal access token. Treat it like a password. The server never logs it.
Configure it. The server reads these environment variables (a
.envfile in the working directory also works):Variable
Required
Default
Purpose
DISCOGS_TOKENyes
Personal access token
DISCOGS_USERNAMEno
auto-detected via
/oauth/identityYour username
DISCOGS_CACHE_PATHno
~/.discogs-mcp/cache.dbSQLite cache location
DISCOGS_ENABLE_LOCALno
falseRegister the digital-library tools
MCP_AUTH_TOKENfor remote HTTP
Bearer token for
--httpCheck it with the MCP Inspector:
DISCOGS_TOKEN=... npx @modelcontextprotocol/inspector uv run discogs-mcp
Related MCP server: Discogs MCP Server
Claude Desktop
Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"discogs": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/discogs-mcp", "run", "discogs-mcp"],
"env": { "DISCOGS_TOKEN": "…", "DISCOGS_USERNAME": "…" }
}
}
}Restart Claude Desktop. If uv isn't found, use its absolute path (which uv). To turn on
the local-library tools, add "DISCOGS_ENABLE_LOCAL": "1" to env and run
uv sync --extra local once.
Claude Code: claude mcp add discogs -e DISCOGS_TOKEN=... -- uv --directory /ABSOLUTE/PATH/discogs-mcp run discogs-mcp
Things to ask
"Sync my Discogs collection, then tell me which labels I own the most of."
"What's in my collection from Warp Records?" This is answered from the cache with no API paging.
"Which pressing of Selected Ambient Works 85–92 do I have, and what's it worth?"
"Styles by decade across my collection."
"Add release 1234 to my wantlist." Claude shows a preview first, and only applies the change after you agree.
Use the identify_pressing prompt with a barcode or runout etching, or crate_dig from a record you love.
Write safety
Every write tool takes
dry_run(defaulttrue) and returns a preview of the change, with the release name, the folder, and the before and after values. Nothing changes until the tool is called again withdry_run=false.Destructive tools (
remove_from_collection,remove_from_wantlist,delete_folder) also needconfirm=true.Tools carry MCP annotations (
readOnlyHint,destructiveHint,idempotentHint), so clients such as Claude Desktop can ask for approval as appropriate.
Local cache
sync_collection copies your folders, collection items (with custom fields such as media
and sleeve condition) and wantlist into SQLite. It takes about 1 request per 100 items, so
a collection of 1,000 records syncs in about 15 requests.
Incremental (the default) fetches only items added since the last sync.
full=truere-reads everything and also picks up removals, folder moves and edits made on the website. If the cached count no longer matches Discogs, the result warns you.sync_release_detailsfetches each release's tracklist and country. It costs one request per release, so it runs in the background, keeps headroom in the rate limit for your other requests, and resumes where it stopped. Check progress withsync_status.query_collection(sql)runs read-only SQL with a 500-row cap. The connection is openedmode=ro, only a singleSELECT/WITHstatement is allowed, and a SQLite authorizer denies anything that isn't a read, includingATTACH,PRAGMAand temp tables. The cache contains:Table or view
Columns
collection(view)instance_id, folder, rating, date_added, fields, release_id, master_id, artist, title, year, labels, catnos, format, formats, genres, styles, country
wants(view)release_id, rating, notes, date_added, plus the release columns
releasesthe release columns above, plus
details_fetched_atrelease_labelsrelease_id, label_id, name, catno
item_fieldsinstance_id, field_id, name, value
tracksrelease_id, position, title, artists, duration, seq
folders,collection_items,wantlist,sync_metalocal_files,local_matchescreated by the local-library tools
labels,catnos,genresandstylesare JSON arrays. Usejson_eachto query them:SELECT s.value AS style, (year/10)*10 AS decade, COUNT(*) AS n FROM collection, json_each(collection.styles) s WHERE year IS NOT NULL GROUP BY 1, 2 ORDER BY n DESC;collection_summaryreturns counts by genre, style, label, artist, decade, format and country, plus duplicates (the same master owned more than once). The same data is available as the resourcediscogs://collection/summary.export_collection(format="csv"|"json", path)writes the cached collection to a file.
Digital library matching (optional)
Turn it on with DISCOGS_ENABLE_LOCAL=1 and uv sync --extra local (this installs
mutagen and rapidfuzz).
scan_local_library(path)reads tags from FLAC, MP3, M4A/ALAC, Ogg, Opus, AIFF, WAV and other formats: artist, album artist, album, year, label, catalog number, barcode andDISCOGS_RELEASE_ID. Files that haven't changed are skipped on later scans.match_local_to_discogs(strategy="cache_first")groups files into albums. An album with aDISCOGS_RELEASE_IDtag matches directly. Other albums are fuzzy-matched on normalized artist and title against your synced collection, and weak matches fall back to Discogs search, capped bymax_api_lookups. The result gives a confidence score and the top 3 candidates for each album that needs review. The full mapping is saved tolocal_matches.export_local_matches(path)writes the mapping as CSV (folder, artist, album, release id, confidence, URL), ready to review or to use for retagging in a tool such as Yate.find_gaps(physical_format="Vinyl")lists records you own on vinyl with no digital copy, and digital albums with no vinyl copy. It compares by master, so a different pressing still counts as a copy.
These tools only read your audio files and never write tags.
Remote HTTP (custom connector)
uv run discogs-mcp --http --port 8765 # http://127.0.0.1:8765/mcp
MCP_AUTH_TOKEN=$(openssl rand -hex 32) uv run discogs-mcp --http --host 0.0.0.0When MCP_AUTH_TOKEN is set, every request must send Authorization: Bearer <token>. The
server refuses to bind to anything other than localhost without a token. On localhost,
DNS-rebinding protection is on.
Keep it local unless you put it behind a tunnel that adds authentication (for example Cloudflare Access or Tailscale). Anyone who can reach the server can act on your Discogs account.
Rate limits and errors
Discogs allows 60 authenticated requests per minute. The client reads
X-Discogs-Ratelimit-Remaining and slows down before it reaches the limit. On a 429 or 5xx
response it backs off with jitter and tries up to 3 times. Errors come back as clear
messages:
Status | Meaning |
401 | Bad token |
404 | Not found |
403 on price suggestions | Discogs only returns price suggestions to accounts with seller settings filled in |
Responses are trimmed before they reach Claude: resource URLs are removed, and so are image
URIs unless you pass include_images=true.
Tool reference
Area | Tools |
Database |
|
User |
|
Marketplace |
|
Collection (read) |
|
Collection (write ✍️) |
|
Wantlist |
|
Cache |
|
Local (optional) |
|
Prompts |
|
Resources |
|
✍️ dry run by default · ⚠️ destructive, also needs confirm=true
Development
uv sync --all-extras
uv run pytest # unit tests, with HTTP mocked by respx
DISCOGS_TOKEN=... uv run pytest -m live # smoke tests against the real APIThe code is laid out as follows:
Path | Contents |
| App setup and transports |
| Rate limiting, retries, pagination and errors |
| Response trimming |
| One module per area |
| SQLite schema, sync logic and the read-only query guard |
| Tag scanning and matching |
Built on the official MCP Python SDK (v2 MCPServer), with httpx and pydantic.
License
MIT
Available Tools
35 toolsadd_to_collectionA
Add a release to a collection folder (default 1 = Uncategorized; 0 is not allowed).
Dry-run by default: returns a preview. Call again with dry_run=false to apply.
Inputs: release_id (required), dry_run, folder_id.
add_to_wantlistAIdempotent
Add a release to the wantlist, or update notes/rating if it's already there.
Dry-run by default: returns a preview. Call again with dry_run=false to apply.
Inputs: release_id (required), notes, rating, dry_run.
collection_summaryBRead-only
Collection overview from the cache: counts by genre, style, label, artist, decade, format and country, duplicate masters (same album owned more than once), and the last sync time.
Inputs: top.
create_folderB
Create a collection folder. Dry-run by default.
Inputs: name (required), dry_run.
delete_folderADestructive
Delete an empty collection folder (not 0 or 1). Destructive: needs dry_run=false AND confirm=true. Discogs refuses to delete folders that still contain items.
Inputs: folder_id (required), confirm, dry_run.
export_collectionB
Write the cached collection to a CSV or JSON file (default ~/.discogs-mcp/collection.).
Inputs: path, format.
find_in_collectionBRead-only
Every copy (instance) of a release in the collection, with folder, rating and fields. Returns an empty list if it is not owned.
Inputs: release_id (required), username.
get_artistCRead-only
Artist profile, real name, aliases, name variations, groups and members.
Inputs: artist_id (required), include_images.
get_artist_releasesCRead-only
An artist's discography (masters and releases, including appearances with roles).
Inputs: artist_id (required), page, sort, per_page, +1 more.
get_collectionARead-only
One page of the collection straight from Discogs (folder 0 = all).
For questions across the whole collection, prefer the cache tools
(query_collection, collection_summary): they avoid paging through the API.
Inputs: page, sort, per_page, username, +2 more.
get_collection_fieldsBRead-only
Custom collection fields (e.g. Media Condition, Sleeve Condition, Notes) and their allowed options. Use the ids with set_collection_field.
Inputs: username.
get_collection_valueBRead-only
Estimated collection value: minimum, median and maximum (based on sales history).
Inputs: username.
get_labelCRead-only
Label profile including parent label and sublabels.
Inputs: label_id (required), include_images.
get_label_releasesCRead-only
Releases on a label, with catalog numbers.
Inputs: label_id (required), page, per_page.
get_listCRead-only
Items in a Discogs list, with each item's comment.
Inputs: list_id (required).
get_masterCRead-only
A master release: the umbrella over every version/pressing of an album.
Inputs: master_id (required), include_images.
get_master_versionsARead-only
List every version (pressing) of a master, with label, catno, country and year.
Filter by format (e.g. "Vinyl"), country, year (`released`) or label. Use it for
"which pressing is this?" then confirm with get_release identifiers.
Inputs: master_id (required), page, sort, year, +5 more.
get_price_suggestionsARead-only
Suggested sale price for each condition grade, based on Discogs sales history.
Discogs only returns this for accounts with seller settings filled in; otherwise it returns a 403 and this tool explains that.
Inputs: release_id (required).
get_releaseBRead-only
Full detail for one release (a specific pressing): tracklist, credits, labels and catalog numbers, formats, identifiers (barcodes, matrix/runout etchings), notes, community have/want and rating.
Inputs: release_id (required), include_images.
get_release_statsBRead-only
Marketplace snapshot for a release: lowest listed price and number for sale.
`currency` is an ISO code such as USD, EUR, GBP (defaults to your account currency).
Inputs: release_id (required), currency.
get_user_listsCRead-only
A user's public lists (defaults to you).
Inputs: page, per_page, username.
get_wantlistARead-only
One page of the wantlist. For whole-wantlist questions, sync_collection and then
query the wants view with query_collection.
Inputs: page, per_page, username.
list_collection_foldersBRead-only
Collection folders with item counts. Folder 0 is "All", 1 is "Uncategorized".
Inputs: username.
move_collection_itemAIdempotent
Move a collection instance to another folder. Dry-run by default.
Inputs: release_id (required), instance_id (required), to_folder_id (required), dry_run.
query_collectionARead-only
Run a read-only SQL SELECT against the local collection cache (max 500 rows). Use it to answer any question across the whole collection without API calls.
Tables and views (SQLite):
collection (view): instance_id, folder_id, folder, rating, date_added, fields, release_id, master_id, artist, title, year, labels, catnos, format, formats, genres, styles, country
wants (view): release_id, rating, notes, date_added, master_id, artist, title, year, labels, catnos, format, formats, genres, styles, country
releases: id, master_id, artist, title, year, labels, catnos, format, formats, genres, styles, country, details_fetched_at
release_labels: release_id, label_id, name, catno (one row per label on a release)
collection_items: instance_id, release_id, folder_id, rating, date_added, fields
item_fields: instance_id, field_id, name, value (e.g. name='Media Condition')
folders: id, name, count
tracks: release_id, position, title, artists, duration, seq (needs sync_release_details)
sync_meta: key, value labels, catnos, genres and styles are JSON arrays: use json_each, e.g. SELECT s.value AS style, COUNT(*) FROM collection, json_each(collection.styles) s GROUP BY 1 fields is a JSON object: json_extract(fields, '$."Media Condition"'). country and tracks are only populated after sync_release_details.
Inputs: sql (required).
rate_collection_itemAIdempotent
Set a 0–5 star rating on a collection instance (0 clears it). Dry-run by default.
Inputs: rating (required), release_id (required), instance_id (required), dry_run.
remove_from_collectionADestructive
Remove one copy (instance) of a release from the collection. Destructive: needs dry_run=false AND confirm=true. Get instance ids from find_in_collection.
Inputs: release_id (required), instance_id (required), confirm, dry_run.
remove_from_wantlistADestructive
Remove a release from the wantlist. Destructive: needs dry_run=false AND confirm=true.
Inputs: release_id (required), confirm, dry_run.
rename_folderBIdempotent
Rename a collection folder (not 0 or 1). Dry-run by default.
Inputs: name (required), folder_id (required), dry_run.
searchARead-only
Search the Discogs database. Combine free-text query with field filters.
Use barcode or catno to pin down a specific pressing. `year` accepts a year or
range like "1990-1995". Returns a compact list; fetch details with get_release /
get_master / get_artist / get_label.
Inputs: page, type, year, catno, +11 more.
set_collection_fieldAIdempotent
Set a custom field (e.g. Media Condition) on a collection instance. For dropdown fields the value must be one of the options from get_collection_fields. Dry-run by default.
Inputs: value (required), field_id (required), release_id (required), instance_id (required), +1 more.
sync_collectionA
Copy the collection, folders and wantlist into the local SQLite cache.
Incremental (default) fetches only items added since the last sync. full=true
re-reads everything and also catches removals, folder moves and edits. Run this
before using query_collection or collection_summary. Tracklists and countries
come from sync_release_details.
Inputs: full.
sync_release_detailsA
Fetch full release detail (tracklist, country) for cached releases that lack it.
Costs one API request per release (Discogs allows 60/min), so by default it runs in
the background and returns immediately; check progress with sync_status. It is
resumable: re-running continues where it stopped. Leaves headroom in the rate limit
for other tools.
Inputs: background, max_releases.
sync_statusBRead-only
Last sync times, cache counts and progress of any background detail fetch.
Inputs: no named parameters.
whoamiARead-only
The authenticated Discogs user: username, profile, collection/wantlist sizes.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Most tools target a distinct resource+action, and descriptions actively disambiguate the riskiest overlaps (e.g. get_collection vs query_collection vs collection_summary vs find_in_collection, and get_release vs get_master vs get_master_versions). A few read paths (collection_summary, query_collection, get_collection) still crowd the same 'read my collection' purpose, but the guidance on when to use each keeps confusion low.
The dominant convention is a clean verb_noun pattern (add_to_collection, remove_from_wantlist, sync_release_details, get_artist_releases, delete_folder, create_folder). A handful of outliers (search, whoami, collection_summary, find_in_collection) break the pattern slightly but remain readable and intuitive.
At 35 tools this is heavy and sits above the comfortable 3-15 range, but the server covers several genuinely distinct domains: collection/folder CRUD, wantlist management, sync/cache, catalog lookup, and marketplace pricing. Nearly every tool has a defensible role, so the count is defensible yet still on the bulky side.
Coverage is broad and well-rounded: full CRUD for collection items and folders, wantlist add/remove/get, sync plus cached querying/export, and lookups for release, master, artist and label with marketplace stats. Only minor gaps exist (e.g. no first-class edit of existing wantlist/list entries beyond the add tool's upsert behavior, limited write surface for user lists).
Related MCP Connectors
Give Claude only the Google Drive files you choose. Every action logged.
tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
CompSniper gives AI assistants real eBay sold prices: up to 240 sold listings per call, 3 years (1,095 days) of eBay sold history on every plan including free, and the real accepted Best Offer price (what the buyer actually paid). 18 marketplaces on one key: 8 eBay sites (US, UK, Germany, France, Italy, Spain, Canada, Australia) plus TCGplayer, PSA, Grailed, Poshmark, Mercari, Depop and the Goldin, Fanatics Collect, Pristine Auction and MySlabs auction houses. Results come raw or AI-cleaned (accessories, lots and wrong models removed), with median, range and shipping. Free plan: 100 requests a month, no card. In the Claude Connectors Directory and ChatGPT Plugins.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to search, manage, and analyze personal Discogs music collections with features like mood-based recommendations, advanced search, and collection analytics.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with your personal Discogs music collection, including search, mood-aware recommendations, collection analytics, and more.13 npmMIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to search, browse, and update a user's music collection, wantlist, folders, ratings, and custom fields, plus retrieve collection statistics and recommendations through natural-language tools.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to query and manage a Discogs music collection in natural language, including collection and catalog search, statistics, recommendations, wantlist and folder updates, ratings, and custom fields. It authenticates with Discogs via OAuth and caches a collection snapshot to answer many queries quickly.13 npmMIT