# MCP VinylShopper

MCP VinylShopper lets an AI assistant work with your record collection through Discogs and search live vinyl listings on eBay.

You can ask in ordinary language:

> “Add this release to my Discogs collection.”

> “Move these records into my Hip-Hop folder.”

> “Show me US sellers offering this pressing on eBay.”

> “What is my collection worth?”

The server translates those requests into official Discogs and eBay API calls. You do not need to know how an API works to use it.

> [!IMPORTANT]
> Some tools can immediately change your real Discogs account. Read **Safety and limitations** before enabling them.

## What is an MCP server?

MCP stands for **Model Context Protocol**. An MCP server is a small bridge between an AI application and another service.

```text
You → AI assistant → MCP VinylShopper → Discogs or eBay
```

The AI never needs your Discogs password. It uses a special Discogs token that you can revoke at any time.

## What it can do

### Discogs

- Search releases, masters, artists, labels, pressings, and prices.
- Read your collection and wantlist.
- Add records and move exact copies between folders.
- Rate records and update custom collection fields.
- Remove exact copies from your collection.
- Create, rename, and delete collection folders.
- Add to or remove from your wantlist.
- Edit supported public profile fields.
- Read and manage seller inventory and marketplace listings.
- Read existing purchases or sales and post order messages.

### eBay

- Search active vinyl listings.
- Filter by price, condition, buying format, seller country, and delivery location.
- Retrieve current details for a specific eBay listing.

eBay support is optional. Discogs features work without eBay credentials.

## What it cannot do

The official Discogs API does **not** provide tools to:

- Put a marketplace item into your buyer cart.
- Place a new Discogs order.
- Complete checkout.
- Charge a card or PayPal account.
- Submit payment.

Those steps must be completed on the Discogs website. MCP VinylShopper intentionally does not imitate or bypass checkout.

## Before you begin

You need:

1. A Mac, Windows PC, or Linux computer.
2. A Discogs account.
3. An MCP-compatible AI application, such as Codex Desktop.
4. [Node.js](https://nodejs.org/) version 22.5 or newer.
5. This project downloaded or cloned to your computer.

If the terms **Terminal**, **environment variable**, or **JSON** are unfamiliar, that is okay. The instructions below show exactly what to do.

## Installation

### 1. Download the project

If Git is installed, open Terminal on macOS/Linux or PowerShell on Windows and run:

```sh
git clone git@github.com:justinmaldonado/MCP_VinylShopper.git
cd MCP_VinylShopper
```

You can also use GitHub’s green **Code** button, choose **Download ZIP**, unzip the download, and open that folder in your terminal.

### 2. Install Node.js

Download the current LTS version from [nodejs.org](https://nodejs.org/). After installing it, close and reopen your terminal, then check the version:

```sh
node --version
```

The number should be `v22.5.0` or newer.

### 3. Install and build MCP VinylShopper

From inside the project folder, run:

```sh
npm install
npm run build
```

When the build succeeds, the usable server is created at `dist/src/index.js`.

## Connect your Discogs account

### 1. Create a Discogs personal access token

1. Sign in to [Discogs](https://www.discogs.com/).
2. Open **Settings**.
3. Select **Developers**.
4. Choose **Generate new token**.
5. Copy the token and save it temporarily in a secure password manager.

A token acts like a key to your account. Anyone who obtains it may be able to read or change your Discogs data.

> [!CAUTION]
> Never post your real token on GitHub, paste it into an issue, include it in a screenshot, or commit it to this repository.

### 2. Add the server to your MCP application

Open your MCP application’s configuration file and add an entry like this:

```json
{
  "mcpServers": {
    "discogs": {
      "command": "node",
      "args": ["/FULL/PATH/TO/MCP_VinylShopper/dist/src/index.js"],
      "env": {
        "DISCOGS_TOKEN": "paste_your_real_discogs_token_here",
        "DISCOGS_USERNAME": "your_discogs_username",
        "DISCOGS_USER_AGENT": "mcp-vinylshopper/0.3.0"
      }
    }
  }
}
```

Replace the full path, token, and username with your own values.

Example macOS path:

```text
/Users/alex/Documents/MCP_VinylShopper/dist/src/index.js
```

Example Windows path in JSON:

```text
C:\\Users\\Alex\\Documents\\MCP_VinylShopper\\dist\\src\\index.js
```

The file [`config/codex-config.example.json`](config/codex-config.example.json) contains a copyable example with placeholders only.

### 3. Restart your MCP application

Completely quit and reopen the application so it starts the new server. Then ask:

> “Use Discogs to verify my identity.”

If the connection works, the assistant should return your Discogs username without displaying your token.

## Optional: connect eBay search

You only need this section if you want live eBay results.

1. Create an account in the [eBay Developer Program](https://developer.ebay.com/).
2. Create an application and choose its **Production** credentials.
3. Copy the **App ID (Client ID)** and **Cert ID (Client Secret)**.
4. Add these fields to the same `env` section in your MCP configuration:

```json
"EBAY_CLIENT_ID": "your_production_app_id",
"EBAY_CLIENT_SECRET": "your_production_cert_id",
"EBAY_MARKETPLACE_ID": "EBAY_US"
```

Restart the MCP application and ask: “Check whether the eBay API is connected.”

These credentials enable listing searches. They do not grant this server permission to buy anything on eBay.

## Everyday examples

- “Search Discogs for the US 7-inch pressing of this song.”
- “Add release 123456 to my Soul folder.”
- “Show every copy of this release in my collection.”
- “Move instance 987654 to my Hip-Hop folder.”
- “Rate this collection copy five stars.”
- “Add this release to my wantlist with a note.”
- “Find eBay copies under $25 that ship to the United States.”
- “List my open marketplace orders.”

For photographs, ask the assistant to identify the exact pressing before adding it. A Discogs **master release** groups many editions; your collection should contain the specific **release** matching your copy.

## Release IDs and instance IDs

- A **release ID** identifies a particular pressing in the Discogs database.
- An **instance ID** identifies one physical copy in your personal collection.

If you own two copies of the same pressing, both use the same release ID but have different instance IDs. Move, edit, and remove tools use the instance ID so the correct copy is changed.

## Safety and limitations

- Write tools act on your real account immediately.
- Removing a collection item, deleting a folder, or deleting a seller listing can be destructive.
- Deleting a Discogs folder causes Discogs to move its records to **Uncategorized**.
- Confirm release and instance IDs before changing duplicate copies.
- Keep account-changing tools behind your MCP application’s approval prompts when possible.
- The general `discogs_api_request` tool can call JSON-based Discogs API v2 paths only on `api.discogs.com`.
- Discogs limits API request frequency. Large jobs may need to pause and continue later.
- Discogs pages and prices can change; search results are not purchase guarantees.

To revoke access, delete the personal token from your Discogs developer settings and remove it from the MCP configuration.

## Plain-English tool reference

### Identity and user information

| Tool | What it does |
| --- | --- |
| `discogs_identity` | Confirms which Discogs account the token belongs to. |
| `get_user_profile` | Reads a Discogs public profile. |
| `edit_user_profile` | Changes supported public profile fields. |
| `get_user_lists` | Shows a user’s public Discogs lists. |
| `get_list` | Opens one Discogs list and its entries. |

### Music database

| Tool | What it does |
| --- | --- |
| `search_database` | Searches releases, masters, artists, and labels. |
| `get_release` | Retrieves one exact pressing and its details. |
| `get_master` | Retrieves the master entry grouping multiple pressings. |
| `get_master_versions` | Lists pressings belonging to a master release. |
| `get_artist` | Retrieves an artist profile. |
| `get_artist_releases` | Lists releases connected to an artist. |
| `get_label` | Retrieves a record-label profile. |
| `get_label_releases` | Lists releases connected to a label. |
| `get_release_rating` | Reads a user’s rating for a release. |
| `set_release_rating` | Creates or changes your release rating. |
| `delete_release_rating` | Removes your release rating. |

### Collection

| Tool | What it does |
| --- | --- |
| `get_collection` | Lists collection items in all folders or one folder. |
| `get_collection_folders` | Lists folder names, IDs, and item counts. |
| `create_collection_folder` | Creates a folder. |
| `rename_collection_folder` | Changes a folder’s name. |
| `delete_collection_folder` | Deletes a folder; Discogs moves its contents to Uncategorized. |
| `find_collection_release` | Finds every owned copy of one release. |
| `add_to_collection` | Adds one copy and returns its new instance ID. |
| `edit_collection_instance` | Moves or rates one exact physical copy. |
| `remove_collection_instance` | Removes one exact copy from the collection. |
| `get_collection_fields` | Lists custom fields such as media or sleeve condition. |
| `set_collection_field` | Sets a custom value on one exact copy. |
| `get_collection_value` | Returns Discogs’ low, median, and high value estimates. |

### Wantlist

| Tool | What it does |
| --- | --- |
| `get_wantlist` | Lists releases on a wantlist. |
| `add_to_wantlist` | Adds or updates a wantlist release, rating, and note. |
| `remove_from_wantlist` | Removes a release from the wantlist. |

### Discogs Marketplace

| Tool | What it does |
| --- | --- |
| `get_price_suggestions` | Returns suggested seller prices by condition. |
| `get_marketplace_stats` | Returns listing count and lowest current price. |
| `get_inventory` | Lists a seller’s inventory. |
| `get_listing` | Retrieves one marketplace listing. |
| `create_listing` | Creates a seller listing. |
| `edit_listing` | Changes a seller listing. |
| `delete_listing` | Deletes a seller listing. |
| `get_orders` | Lists authenticated purchases and sales. |
| `get_order` | Retrieves one existing order. |
| `edit_order` | Changes supported status or shipping details on an existing order. |
| `get_order_messages` | Reads messages on an order. |
| `post_order_message` | Posts a message on an order. |
| `get_fee` | Estimates a marketplace fee. |
| `get_currency_exchange_rates` | Retrieves Discogs exchange rates. |

### eBay and advanced access

| Tool | What it does |
| --- | --- |
| `ebay_api_status` | Checks whether eBay credentials work. |
| `search_ebay_vinyl` | Searches active eBay vinyl listings with filters. |
| `get_ebay_item` | Retrieves current details for one eBay item. |
| `discogs_api_request` | Calls another JSON Discogs API v2 endpoint using a safe relative path. Intended for advanced users. |

## Troubleshooting

### “Provide username or set DISCOGS_USERNAME”

Add `DISCOGS_USERNAME` to the MCP configuration, then restart the application.

### “Discogs API 401” or “You must authenticate”

The token is missing, incorrect, expired, or revoked. Generate a new Discogs token and update the configuration.

### “Server disconnected” or the tools do not appear

1. Confirm the path to `dist/src/index.js` is absolute and correct.
2. Run `npm install` and `npm run build` again.
3. Completely restart the MCP application.
4. Check that `node --version` is 22.5 or newer.

### Changes to the code do not appear

Run `npm run build`, then restart the MCP application. It runs the compiled file in `dist`, not the TypeScript source directly.

### eBay tools report missing credentials

Discogs will continue to work. Either add the optional eBay settings or do not use the eBay tools.

### An API request is rejected during a large job

Discogs paginates results and limits request frequency. Wait briefly and retry, or process the job in smaller groups.

## Developer commands

```sh
npm install       # Install dependencies
npm run typecheck # Check TypeScript without producing build files
npm test          # Build and run all automated tests
npm run build     # Compile TypeScript into dist/
npm start         # Run the compiled MCP server
```

The server requires Node.js 22.5 or newer. Network requests time out after 15 seconds. Discogs pages return at most 100 items per request, and eBay search returns at most 200.

## Credential files

- `.env` is ignored by Git and is safe for local experimentation.
- `.env.example` contains placeholders and may be committed.
- `config/codex-config.example.json` contains placeholders and may be committed.
- Do not place real credentials into any tracked file.

## Project status

This is an unofficial community project. It is not affiliated with, endorsed by, or supported by Discogs or eBay. API behavior may change when those services update their platforms.

## License

No open-source license has been added yet. Unless a license is added, the repository remains copyrighted and reuse rights are not automatically granted.