Skip to main content
Glama

discogs-mcp (Discogs MCP connector)

Local MCP connector for the Discogs API. One user, bring-your-own personal access token, stdio by default. HTTP mode binds to 127.0.0.1 and is not a hosted service.

This application uses Discogs' API but is not affiliated with, sponsored or endorsed by Discogs. "Discogs" is a trademark of Zink Media, LLC.

The registry covers 60 of the 62 operations in discogs.openapi.json. Two OAuth 1.0a endpoints are excluded because this connector uses personal access tokens only. scripts/gen-operations.mjs holds that allow-list, and test/operations.test.ts repeats it. Image URLs are not an endpoint. Parsers drop image fields and never fetch them.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.

Create a Discogs personal access token in the Discogs developer settings. Put it in DISCOGS_TOKEN. The connector sends Authorization: Discogs token=<token> and never puts the token in the query string.

{
  "mcpServers": {
    "discogs": {
      "command": "node",
      "args": ["/workspace/connectors/discogs/dist/index.js"],
      "env": {
        "DISCOGS_TOKEN": "...",
        "DISCOGS_CONTACT": "you@example.com",
        "DISCOGS_ALLOW_WRITES": "false",
        "DISCOGS_TOOLSETS": "database,user,collection,wantlist,lists"
      }
    }
  }
}

Docker (HTTP, no authentication, localhost only):

docker build -t discogs .
docker run -p 127.0.0.1:3000:3000 \
  -e DISCOGS_TOKEN=... \
  -e DISCOGS_CONTACT=you@example.com \
  discogs

Do not put tokens in the image.

Regenerate the operations registry after a spec change:

npm run gen:operations

Related MCP server: mcp-discogs

Config

Variable

Meaning

DISCOGS_TOKEN

Personal access token. Required unless DISCOGS_ANONYMOUS=true. At least 8 characters. Sent as Authorization: Discogs token=<token>.

DISCOGS_CONTACT

Required. Email or http(s) URL. Used in the User-Agent GrokBotConnectorForDiscogs/0.1 (+<contact>). The server refuses to start without it.

DISCOGS_ANONYMOUS

Set to true for public read-only calls with no token (25 requests per minute). Database toolset plus marketplace stats only.

DISCOGS_ALLOW_WRITES

Must be the literal true before a confirmed write is sent.

DISCOGS_USERNAME

Default username path parameter. If unset, the connector calls GET /oauth/identity once and caches the name in memory.

DISCOGS_TOOLSETS

Comma list of toolsets, or all. Default info,database,user,collection,wantlist,lists. marketplace and inventory are opt-in.

DISCOGS_CACHE_TTL_SECONDS

In-memory TTL for public database GETs. Default 300. Hard cap 21600 (6 hours). Larger values are rejected.

DISCOGS_MAX_CSV_BYTES

Inventory CSV size cap. Default 1000000.

DISCOGS_BASE_URL

Override for tests. Default https://api.discogs.com. Must be https, or http on 127.0.0.1 or localhost.

DISCOGS_TIMEOUT_MS

Upstream timeout. Default 20000.

MCP_TRANSPORT

stdio or http. --http overrides.

PORT

HTTP port. Default 3000. Bound to 127.0.0.1.

Invalid values are reported by field name and issue code. The rejected value is not included. The token is redacted in logs, errors, tool results, thrown messages, and URLs.

Without DISCOGS_TOKEN and without DISCOGS_ANONYMOUS=true the server refuses to start.

Toolsets and tools

Eight tools. discogs_info is always on. Each other tool takes an action enum.

Tool

Default

Actions

discogs_info

always

Connector version, toolsets, writes, rate-limit state, cache TTL, attribution, terms note.

discogs_database

yes

search, get_release, get_release_rating, get_release_stats, get_user_release_rating, get_master, get_master_versions, get_artist, get_artist_releases, get_label, get_label_releases

discogs_user

yes

get_identity, get_profile, edit_profile, list_submissions, list_contributions

discogs_collection

yes

list_folders, create_folder, get_folder, update_folder, delete_folder, list_folder_releases, find_release, add_release, update_instance, delete_instance, list_fields, update_field, get_value, set_release_rating, delete_release_rating

discogs_wantlist

yes

list, add, update, delete

discogs_lists

yes

list, get

discogs_marketplace

opt-in

list_inventory, get_listing, create_listing, update_listing, delete_listing, list_orders, get_order, update_order, list_messages, create_message, get_fee, get_fee_for_currency, get_price_suggestions, get_stats

discogs_inventory

opt-in

request_export, list_exports, get_export, download_export, list_uploads, get_upload, upload_add, upload_change, upload_delete

Marketplace and inventory carry buyer addresses and seller data (Restricted Data). Enable them with DISCOGS_TOOLSETS.

Anonymous mode publishes discogs_info, discogs_database, and discogs_marketplace. Search and every user or write action is refused.

Folder 0 is All. Folder 1 is Uncategorized. Folder 0 and folder 1 cannot be edited or deleted. Add a release to folder 1, not folder 0.

include_image_urls is an optional boolean on every tool. Default drops images, thumb, cover_image, and avatar_url. When true, those fields become URL strings. The connector never fetches images.

Inventory upload actions take body.csv as a string. Headers are lowercased. Required columns: add needs release_id,price,media_condition; change needs release_id plus at least one other field; delete needs listing_id. The dry-run preview shows the row count and the first 5 rows. Export download returns CSV text capped at 200 data rows plus total_rows and truncated.

Write safety

Writes need confirm set to the boolean true and DISCOGS_ALLOW_WRITES=true. Omit confirm for a dry-run preview (method, path, redacted body, summary, what_would_change). The preview does not send a request. confirm: true with writes disabled returns a blocked preview.

Destructive operations are flagged: delete folder, delete collection instance, delete wantlist item, delete listing, delete rating, inventory delete CSV, and order status changes to Cancelled* or Refund Sent. Shipping and status cannot be set in the same order edit.

Rate limits

Authenticated traffic is capped at 60 requests per minute. Anonymous traffic is capped at 25. A local sliding window runs in addition to Discogs headers X-Discogs-Ratelimit, X-Discogs-Ratelimit-Used, and X-Discogs-Ratelimit-Remaining. When remaining is 2 or less the client waits for the window. On HTTP 429 it honors Retry-After if present, otherwise it waits for the next window, retries at most once, then returns a typed rate-limit error.

Requests send Accept: application/vnd.discogs.v2.plaintext+json.

Terms and data use

Every successful tool result includes attribution ("Data provided by Discogs. https://www.discogs.com") and fetched_at (ISO-8601). The full non-affiliation notice lives in the server instructions and in this README. It is not repeated as a long block on every result.

API data is cached in memory only. The connector never writes Discogs payloads to disk. Only public database GETs are cached. Collection, wantlist, marketplace, lists, and profile responses are not cached. The TTL cannot exceed 6 hours. Treat cached public data as no fresher than that cap.

Restricted Data (collections, wantlists, marketplace, images, user data) is for personal use by the token holder. No commercial use, no transfer to third parties, no sublicensing. This connector must remain free. Do not use it to charge for Discogs data. Do not bulk-copy Discogs data.

Comparison with cswkim/discogs-mcp-server

cswkim/discogs-mcp-server publishes many flat tools. This connector publishes eight tools with action enums, confirm-gated writes with dry-run previews, inventory CSV add/change/delete with validation, order tracking, price suggestions/fee/stats, per-user release ratings, attribution and Restricted-Data handling, Discogs rate-limit headers, typed parsers, and spec-coverage tests. Those differences are from reading that project's public description and from this repo's tests. This README does not claim a live run of the other server.

Live check

See LIVE-CHECK.md. Run node scripts/live-check.mjs --mock against the built stdio server. --live-public is a small anonymous check the operator runs. --live-token runs only when DISCOGS_TOKEN is set and prints no secrets.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Discogs project or its owners.

Available Tools

6 tools
discogs_collectionA
DestructiveIdempotent

discogs_collection covers the collection toolset (15 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Writes need confirm set to the boolean true and DISCOGS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that does not send the request. Actions: add_release: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}. Add a release to a collection folder. Add targets folder 1 (Uncategorized), not folder 0 (All). create_folder: POST /users/{username}/collection/folders. Create a collection folder. delete_folder: DELETE /users/{username}/collection/folders/{folder_id}. Delete a collection folder. Folder 0 and folder 1 cannot be deleted. Warning: This deletes a collection folder. Folder 0 (All) and folder 1 (Uncategorized) cannot be deleted. delete_instance: DELETE /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}. Remove a release instance from the collection. Warning: This removes a release instance from the collection. delete_release_rating: DELETE /releases/{release_id}/rating/{username}. Delete the authenticated user's rating for a release. Warning: This deletes the user's rating for the release. find_release: GET /users/{username}/collection/releases/{release_id}. Find a release across collection folders. get_folder: GET /users/{username}/collection/folders/{folder_id}. Get one collection folder. get_value: GET /users/{username}/collection/value. Get the estimated value of the collection. list_fields: GET /users/{username}/collection/fields. List custom collection fields. list_folder_releases: GET /users/{username}/collection/folders/{folder_id}/releases. List releases in a collection folder. list_folders: GET /users/{username}/collection/folders. List collection folders. Folder 0 is All. Folder 1 is Uncategorized. set_release_rating: PUT /releases/{release_id}/rating/{username}. Set the authenticated user's rating (1-5) for a release. update_field: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}/fields/{field_id}. Set a custom field value on a collection instance. update_folder: POST /users/{username}/collection/folders/{folder_id}. Rename a collection folder. Folder 0 and folder 1 cannot be edited. update_instance: POST /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}. Change the rating of a collection instance or move it to another folder.

Inputs: action (required), body, query, params, +2 more.

discogs_databaseA
Read-only

discogs_database covers the database toolset (11 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Actions: get_artist: GET /artists/{artist_id}. Get one artist by id. get_artist_releases: GET /artists/{artist_id}/releases. List releases for an artist. get_label: GET /labels/{label_id}. Get one label by id. get_label_releases: GET /labels/{label_id}/releases. List releases for a label. get_master: GET /masters/{master_id}. Get one master release by id. get_master_versions: GET /masters/{master_id}/versions. List versions of a master release. get_release: GET /releases/{release_id}. Get one release by id. get_release_rating: GET /releases/{release_id}/rating. Get the community rating for a release. get_release_stats: GET /releases/{release_id}/stats. Get community stats for a release (have, want). get_user_release_rating: GET /releases/{release_id}/rating/{username}. Get one user's rating for a release. search: GET /database/search. Search the Discogs database. Requires a token. Anonymous search is refused by Discogs.

Inputs: action (required), body, query, params, +1 more.

discogs_infoB
Read-only

Connector status: version, enabled toolsets, writes, rate-limit state, cache TTL, attribution, and a terms note. Always on.

Inputs: include_image_urls.

discogs_listsA
Read-only

discogs_lists covers the lists toolset (2 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Actions: get: GET /lists/{list_id}. Get one list by id. list: GET /users/{username}/lists. List a user's lists.

Inputs: action (required), body, query, params, +1 more.

discogs_userA

discogs_user covers the user toolset (5 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Writes need confirm set to the boolean true and DISCOGS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that does not send the request. Actions: edit_profile: POST /users/{username}. Edit the authenticated user's profile. get_identity: GET /oauth/identity. Return the identity of the authenticated token holder. get_profile: GET /users/{username}. Get a user profile. Profile HTML/BBCode is requested as plaintext. list_contributions: GET /users/{username}/contributions. List a user's contributions. list_submissions: GET /users/{username}/submissions. List a user's submissions.

Inputs: action (required), body, query, params, +2 more.

discogs_wantlistA
DestructiveIdempotent

discogs_wantlist covers the wantlist toolset (4 operations). Token is sent as Authorization: Discogs token= and never in the query string. Local stdio server for one user. Not a hosted service. Writes need confirm set to the boolean true and DISCOGS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that does not send the request. Actions: add: POST /users/{username}/wants/{release_id}. Add a release to the wantlist. delete: DELETE /users/{username}/wants/{release_id}. Remove a release from the wantlist. Warning: This removes a release from the wantlist. list: GET /users/{username}/wants. List the user's wantlist. update: PUT /users/{username}/wants/{release_id}. Add or update a wantlist item (notes, rating).

Inputs: action (required), body, query, params, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct Discogs domain: info, collection, database, lists, user, and wantlist. Boundaries are mostly clear, though rating-related operations are split between discogs_collection and discogs_database, which could cause some hesitation.

    Naming Consistency5/5

    All tools follow a consistent discogs_<domain> snake_case pattern. The convention is predictable and uniform across the entire set.

    Tool Count5/5

    Six top-level tools is well-scoped for a Discogs MCP, with related operations grouped into domain-specific toolsets rather than exposing dozens of individual endpoints. Each tool earns its place.

    Completeness5/5

    The surface covers the major Discogs areas: collection CRUD/folders/fields/value/ratings, database artist/label/master/release/search, lists, user profile/submissions/contributions, and wantlist operations. No obvious workflow dead ends are apparent for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables interactions with the Discogs API for music catalog operations and search functionality, allowing users to manage their Discogs collections through natural language.
      53
      160 npm
      134
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying music discography data from Discogs, including master releases, artist profiles, and label information.
      88 npm
      1
      MIT
    • 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 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