discogs-mcp
Provides tools for interacting with the Discogs API, including catalog search and retrieval for releases, masters, artists, and labels; managing user profiles, collections, folders, wantlists, and lists; and opt-in marketplace and inventory operations such as listings, orders, messages, fees, and CSV uploads/exports.
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 find original 1979 UK pressings of Unknown Pleasures on Discogs"
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 (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:httpnpm 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 \
discogsDo not put tokens in the image.
Regenerate the operations registry after a spec change:
npm run gen:operationsRelated MCP server: mcp-discogs
Config
Variable | Meaning |
| Personal access token. Required unless |
| Required. Email or http(s) URL. Used in the User-Agent |
| Set to |
| Must be the literal |
| Default |
| Comma list of toolsets, or |
| In-memory TTL for public database GETs. Default 300. Hard cap 21600 (6 hours). Larger values are rejected. |
| Inventory CSV size cap. Default 1000000. |
| Override for tests. Default |
| Upstream timeout. Default 20000. |
|
|
| 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 |
| always | Connector version, toolsets, writes, rate-limit state, cache TTL, attribution, terms note. |
| 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 |
| yes | get_identity, get_profile, edit_profile, list_submissions, list_contributions |
| 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 |
| yes | list, add, update, delete |
| yes | list, get |
| 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 |
| 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 toolsdiscogs_collectionADestructiveIdempotent
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_databaseARead-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_infoBRead-only
Connector status: version, enabled toolsets, writes, rate-limit state, cache TTL, attribution, and a terms note. Always on.
Inputs: include_image_urls.
discogs_listsARead-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_wantlistADestructiveIdempotent
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
Scored across 6 tools
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.
All tools follow a consistent discogs_<domain> snake_case pattern. The convention is predictable and uniform across the entire set.
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.
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
Related MCP Connectors
Discogs MCP server for ChatGPT, Claude and any AI agent: search releases, list copies for sale, add release to collection, add release to wantlist, reprice listing, update order status and message buyer in your own Discogs account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Discogs yourself; Cotlet does not store your password and you need no Discogs API key. About the official Discogs API: Discogs has a full REST API, version 2, that covers the database, collections, wantlists, marketplace inventory and orders, but no official MCP server (checked 17 Oct 2026). Authenticated requests are limited to 60 per minute and unauthenticated ones to 25. Setup and FAQ: https://cotlet.dev/integrations/discogs-api-mcp-server
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Search MusicBrainz artists, releases, works, labels; resolve ISRC/ISWC/barcode; fetch cover art.
Unofficial, read-only access to your Last.fm listening history, charts, and music lookups.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables interactions with the Discogs API for music catalog operations and search functionality, allowing users to manage their Discogs collections through natural language.53160 npm134MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying music discography data from Discogs, including master releases, artist profiles, and label information.88 npm1MIT
- 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 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