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

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.

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.