Skip to main content
Glama
discogs-mcp
by hlights33

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_collection once, then use read-only SQL (query_collection) and collection_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

  1. 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 tools
  2. Get 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.

  3. Configure it. The server reads these environment variables (a .env file in the working directory also works):

    Variable

    Required

    Default

    Purpose

    DISCOGS_TOKEN

    yes

    Personal access token

    DISCOGS_USERNAME

    no

    auto-detected via /oauth/identity

    Your username

    DISCOGS_CACHE_PATH

    no

    ~/.discogs-mcp/cache.db

    SQLite cache location

    DISCOGS_ENABLE_LOCAL

    no

    false

    Register the digital-library tools

    MCP_AUTH_TOKEN

    for remote HTTP

    Bearer token for --http

  4. Check 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 (default true) 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 with dry_run=false.

  • Destructive tools (remove_from_collection, remove_from_wantlist, delete_folder) also need confirm=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=true re-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_details fetches 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 with sync_status.

  • query_collection(sql) runs read-only SQL with a 500-row cap. The connection is opened mode=ro, only a single SELECT/WITH statement is allowed, and a SQLite authorizer denies anything that isn't a read, including ATTACH, PRAGMA and 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

    releases

    the release columns above, plus details_fetched_at

    release_labels

    release_id, label_id, name, catno

    item_fields

    instance_id, field_id, name, value

    tracks

    release_id, position, title, artists, duration, seq

    folders, collection_items, wantlist, sync_meta

    local_files, local_matches

    created by the local-library tools

    labels, catnos, genres and styles are JSON arrays. Use json_each to 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_summary returns 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 resource discogs://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).

  1. 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 and DISCOGS_RELEASE_ID. Files that haven't changed are skipped on later scans.

  2. match_local_to_discogs(strategy="cache_first") groups files into albums. An album with a DISCOGS_RELEASE_ID tag 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 by max_api_lookups. The result gives a confidence score and the top 3 candidates for each album that needs review. The full mapping is saved to local_matches.

  3. 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.

  4. 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.0

When 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

search, get_release, get_master, get_master_versions, get_artist, get_artist_releases, get_label, get_label_releases

User

whoami, get_user_lists, get_list

Marketplace

get_release_stats, get_price_suggestions, get_collection_value

Collection (read)

list_collection_folders, get_collection, find_in_collection, get_collection_fields

Collection (write ✍️)

add_to_collection, move_collection_item, rate_collection_item, set_collection_field, create_folder, rename_folder, remove_from_collection ⚠️, delete_folder ⚠️

Wantlist

get_wantlist, add_to_wantlist ✍️, remove_from_wantlist ⚠️

Cache

sync_collection, sync_release_details, sync_status, query_collection, collection_summary, export_collection

Local (optional)

scan_local_library, match_local_to_discogs, export_local_matches, find_gaps

Prompts

identify_pressing, crate_dig

Resources

discogs://collection/summary

✍️ 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 API

The code is laid out as follows:

Path

Contents

src/discogs_mcp/server.py

App setup and transports

client.py

Rate limiting, retries, pagination and errors

models.py

Response trimming

tools/

One module per area

cache/

SQLite schema, sync logic and the read-only query guard

local/

Tag scanning and matching

Built on the official MCP Python SDK (v2 MCPServer), with httpx and pydantic.

License

MIT

Available Tools

35 tools
add_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_wantlistA
Idempotent

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_summaryB
Read-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_folderA
Destructive

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_collectionB
Read-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_artistC
Read-only

Artist profile, real name, aliases, name variations, groups and members.

Inputs: artist_id (required), include_images.

get_artist_releasesC
Read-only

An artist's discography (masters and releases, including appearances with roles).

Inputs: artist_id (required), page, sort, per_page, +1 more.

get_collectionA
Read-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_fieldsB
Read-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_valueB
Read-only

Estimated collection value: minimum, median and maximum (based on sales history).

Inputs: username.

get_labelC
Read-only

Label profile including parent label and sublabels.

Inputs: label_id (required), include_images.

get_label_releasesC
Read-only

Releases on a label, with catalog numbers.

Inputs: label_id (required), page, per_page.

get_listC
Read-only

Items in a Discogs list, with each item's comment.

Inputs: list_id (required).

get_masterC
Read-only

A master release: the umbrella over every version/pressing of an album.

Inputs: master_id (required), include_images.

get_master_versionsA
Read-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_suggestionsA
Read-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_releaseB
Read-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_statsB
Read-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_listsC
Read-only

A user's public lists (defaults to you).

Inputs: page, per_page, username.

get_wantlistA
Read-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_foldersB
Read-only

Collection folders with item counts. Folder 0 is "All", 1 is "Uncategorized".

Inputs: username.

move_collection_itemA
Idempotent

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_collectionA
Read-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_itemA
Idempotent

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_collectionA
Destructive

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_wantlistA
Destructive

Remove a release from the wantlist. Destructive: needs dry_run=false AND confirm=true.

Inputs: release_id (required), confirm, dry_run.

rename_folderB
Idempotent

Rename a collection folder (not 0 or 1). Dry-run by default.

Inputs: name (required), folder_id (required), dry_run.

set_collection_fieldA
Idempotent

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_statusB
Read-only

Last sync times, cache counts and progress of any background detail fetch.

Inputs: no named parameters.

whoamiA
Read-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

    B3.3/5.0

    Scored across 35 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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.

      https://sharewatch.ai/mcp
    • 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).

      https://tri-train.com/api/mcp
    • 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.

      https://mcp.compsniper.com/mcp

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to search, manage, and analyze personal Discogs music collections with features like mood-based recommendations, advanced search, and collection analytics.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with your personal Discogs music collection, including search, mood-aware recommendations, collection analytics, and more.
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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 npm
      MIT