# discogs-mcp

[![CI](https://github.com/Spiegelberg/discogs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Spiegelberg/discogs-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/discogs-mcp.svg)](https://www.npmjs.com/package/discogs-mcp)

A [Model Context Protocol](https://modelcontextprotocol.io) server for [Discogs](https://www.discogs.com). Search the
catalog, manage your collection and wantlist, and work the marketplace — straight from Claude or any other MCP
client. No hosting required: it runs locally via `npx` and talks to Discogs' own API directly.

## Features

| Area | Tools |
| --- | --- |
| Identity | `discogs_whoami` |
| Catalog | `discogs_search`, `discogs_get_release`, `discogs_get_master`, `discogs_get_master_versions`, `discogs_get_artist`, `discogs_get_artist_releases`, `discogs_get_label`, `discogs_get_label_releases` |
| Collection | `discogs_list_collection_folders`, `discogs_get_collection_items`, `discogs_add_to_collection`, `discogs_remove_from_collection`, `discogs_update_collection_item`, `discogs_get_collection_value` |
| Wantlist | `discogs_get_wantlist`, `discogs_add_to_wantlist`, `discogs_remove_from_wantlist` |
| Marketplace | `discogs_get_marketplace_stats`, `discogs_get_price_suggestions`, `discogs_get_listing`, `discogs_get_seller_inventory`, `discogs_create_listing`, `discogs_update_listing`, `discogs_delete_listing` |
| Orders | `discogs_list_orders`, `discogs_get_order`, `discogs_update_order`, `discogs_list_order_messages`, `discogs_add_order_message` |

## Quick start — personal access token (recommended)

The simplest setup: no app registration, no OAuth flow, just one token.

1. Go to [discogs.com/settings/developers](https://www.discogs.com/settings/developers) and click
   **Generate new token** under **Personal access tokens**.
2. Add discogs-mcp to your MCP client with that token.

### Claude Code

```bash
claude mcp add discogs -e DISCOGS_PERSONAL_TOKEN=your_token -- npx -y discogs-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": ["-y", "discogs-mcp"],
      "env": {
        "DISCOGS_PERSONAL_TOKEN": "your_token"
      }
    }
  }
}
```

Restart your client and the `discogs_*` tools will appear.

## Alternative — OAuth app (for multi-user or CI setups)

If you need to authenticate as a different Discogs user than the token owner, or want to use
[OAuth 1.0a](https://www.discogs.com/developers#page:authentication) app credentials instead:

1. Register a free application at [discogs.com/settings/developers](https://www.discogs.com/settings/developers)
   — any name works; grab the **Consumer Key** and **Consumer Secret**.
2. Run the login flow to authorize and save an access token:

```bash
export DISCOGS_CONSUMER_KEY=your_consumer_key
export DISCOGS_CONSUMER_SECRET=your_consumer_secret

npx discogs-mcp login
```

This opens your browser to Discogs' authorization page and saves the access token to
`~/.config/discogs-mcp/credentials.json` (mode `0600`). You only need to do this once.

Then add to your MCP client with the consumer credentials so the server can sign requests:

```bash
# Claude Code
claude mcp add discogs -e DISCOGS_CONSUMER_KEY=your_key -e DISCOGS_CONSUMER_SECRET=your_secret -- npx -y discogs-mcp
```

## Remote server (Cloudflare Worker)

Want to add Discogs as a **custom connector** in Claude instead of running it locally?
The [`worker/`](./worker) directory is a read-only remote MCP server (Streamable HTTP)
you can deploy to Cloudflare Workers in a few clicks — no `npx` process on your machine.
See [worker/README.md](./worker/README.md) for the one-time setup.

## Environment variables

| Variable | Required | Purpose |
| --- | --- | --- |
| `DISCOGS_PERSONAL_TOKEN` | One of these two auth methods | Personal access token from discogs.com/settings/developers. Simplest option — no app or login step needed. |
| `DISCOGS_CONSUMER_KEY` / `DISCOGS_CONSUMER_SECRET` | One of these two auth methods | OAuth app credentials. Required when using the `login` flow or injecting OAuth access tokens via env vars. |
| `DISCOGS_ACCESS_TOKEN` / `DISCOGS_ACCESS_TOKEN_SECRET` | No | Inject an OAuth access token directly (skips the on-disk credential file — useful for CI). Both must be set together, alongside the consumer key/secret. |
| `DISCOGS_USERNAME` | No | Skip the automatic username lookup on startup. Optional speed-up when the username is already known. |
| `DISCOGS_USER_AGENT` | No | Overrides the `User-Agent` header. Defaults to `discogs-mcp/<version> +<repo url>`. |
| `DISCOGS_MCP_CREDENTIALS_PATH` | No | Overrides where `login` reads/writes credentials. Defaults to `~/.config/discogs-mcp/credentials.json`. |

## Security notes

- The access token/secret saved by `login` are only as sensitive as your Discogs account — they grant the same
  access you approved (collection, wantlist, marketplace, orders). The file is written with `0600` permissions.
- You can revoke access at any time from your Discogs account under **Settings → Developers**, then delete
  `~/.config/discogs-mcp/credentials.json` locally.
- Tools that create, modify, or delete marketplace listings/orders are real, live actions — most MCP clients ask
  for confirmation before running a tool call, but treat those tools as if they were.
- See [SECURITY.md](./SECURITY.md) for how to report a vulnerability.

## Development

```bash
git clone https://github.com/Spiegelberg/discogs-mcp.git
cd discogs-mcp
npm install

npm run dev        # run the server against source with tsx
npm run lint
npm run typecheck
npm test
npm run build       # bundle to dist/
```

See [CONTRIBUTING.md](./CONTRIBUTING.md) for more.

## Publishing / distribution checklist

Automated by this repo:

- [x] `npm run build` produces a working `dist/index.js` bin.
- [x] CI (`.github/workflows/ci.yml`) lints, typechecks, tests, and builds on every push/PR.
- [x] Pushing a `vX.Y.Z` tag runs `.github/workflows/publish.yml`, which publishes to npm with
      [provenance](https://docs.npmjs.com/generating-provenance-statements).
- [x] `server.json` is ready to submit to the open [MCP Registry](https://github.com/modelcontextprotocol/registry)
      via the `mcp-publisher` CLI, and `package.json`'s `mcpName` field matches it.

Still manual, and outside what code in this repo can do:

- [ ] Create/own the `discogs-mcp` npm package and add an `NPM_TOKEN` repo secret so the publish workflow can run.
- [ ] Run `mcp-publisher` (or open a PR against the MCP Registry) to list it there.
- [ ] If you want it in Anthropic's curated in-product connector directory, that's a separate outreach/review
      process with Anthropic — not something a GitHub Action can trigger.

## License

[MIT](./LICENSE)