Discogs

What is Discogs MCP Server?

Discogs MCP Server is a Model Context Protocol (MCP) server designed to interact with the Discogs API. It enables users to manage their music collection, perform searches, and execute various music-related operations through an MCP client like Claude Desktop.

How to use Discogs MCP Server?

There are several ways to use the Discogs MCP Server:

• NPX (Recommended for quick start): Directly run from the npm registry using npx -y discogs-mcp-server.
• Local Node: Install dependencies (pnpm install) and run the server locally using Node.js.
• Docker: Build a Docker image and run the server in a container.

Before running, ensure you have Node.js (or Docker) and your Discogs personal access token. The server can be configured with MCP clients like Claude Desktop by adding specific JSON configurations to claude_desktop_config.json.

Key Features of Discogs MCP Server

• Discogs API Integration: Seamlessly connects to the Discogs API for music collection management.
• Music Catalog Operations: Enables operations like managing your music collection.
• Search Functionality: Provides tools for searching the Discogs database.
• Multiple Deployment Options: Supports local development, Docker, and direct execution via NPX.
• MCP Inspector: Includes a tool to test and inspect your local MCP server.
• Built with FastMCP: Leverages the FastMCP framework for robust MCP server development.

Use Cases of Discogs MCP Server

• Music Collection Management: Users can interact with and manage their Discogs music collection programmatically.
• Automated Music Data Retrieval: Developers can build applications that automatically fetch music information from Discogs.
• Integration with AI Assistants: Integrate Discogs functionalities into AI assistants (like Claude Desktop) for natural language interaction with music data.
• Data Editing: Allows for editing data within your Discogs collection (use with caution).

FAQ from Discogs MCP Server

• Q: What are the caveats of using this server?
  • A: The Discogs API documentation may have inconsistencies. Type safety is not verified for every response due to the vast number of endpoints. Editing data in your Discogs collection should be done with caution.
• Q: What are the prerequisites?
  • A: Node.js (tested with 20.x.x, 18.x.x should work) and optionally Docker.
• Q: How do I get my Discogs personal access token?
  • A: Go to your Discogs Settings > Developers page.
• Q: What is the default per_page value for Discogs API requests?
  • A: The project sets discogs.config.defaultPerPage to 5 to avoid overwhelming clients, though the Discogs API default is 50.
• Q: What MCP clients are supported?
  • A: Currently, it has only been tested with Claude Desktop.
• Q: Will OAuth support be added?
  • A: Yes, OAuth support is planned for a future release.
• Q: What is the license?
  • A: The project is licensed under the MIT License.

Discogs MCP Server

MCP Server for the Discogs API, enabling music catalog operations, search functionality, and more.

Quickstart

If you just want to get started immediately using this MCP Server with the Claude desktop app and don't care about development or running the server yourself, then make sure you have Node.js installed and your Discogs personal access token ready and skip straight to the Claude configuration section. Use the NPX method from that section.

Table of Contents

• Acknowledgements
• Available Tools
• Caveats
• Prerequisites
• Setup
• Running the Server
  • Option 1: Local Development
  • Option 2: Docker
• Inspection
• MCP Clients
  • Claude Desktop Configuration
    • NPX
    • Local Node
    • Docker
• TODO
• License

Acknowledgements

This MCP server is built using FastMCP, a typescript framework for building MCP servers. For more information about MCP and how to use MCP servers, please refer to the FastMCP documentation and the official MCP documentation.

Available Tools

Check out the list of available tools: TOOLS.md

Caveats

• The Discogs API documentation is not perfect and some endpoints may not be fully documented or may have inconsistencies.
• Due to the vast number of API endpoints and response types, it's not feasible to verify type safety for every possible response. Please report any type-related issues you encounter.
• This MCP server allows for editing data in your Discogs collection. Please use with caution and verify your actions before executing them.
• The Discogs API per_page default is 50, which can be too much data for some clients to process effectively, so within this project a discogs.config.defaultPerPage value has been set to 5. You can request more data in your prompts, but be aware that some clients may struggle with larger responses.

Prerequisites

• Node.js (tested with Node.js 20.x.x, but 18.x.x should work as well)
  • Check your Node.js version with: node --version
• Docker (optional, for running a local docker image without having to deal with Node or dependencies)

Setup

1. Clone the repository
2. Create a .env file in the root directory based on .env.example
3. Set the following required environment variables in your .env:
   • DISCOGS_PERSONAL_ACCESS_TOKEN: Your Discogs personal access token

To get your Discogs personal access token, go to your Discogs Settings > Developers page and find your token or generate a new one. DO NOT SHARE YOUR TOKEN. OAuth support will be added in a future release.

The other environment variables in .env.example are optional and have sensible defaults, so you don't need to set them unless you have specific requirements.

Running the Server Locally

Option 1: Local Development

1. Install dependencies:

   pnpm install
   

2. Available commands:

   • pnpm run dev: Start the development server with hot reloading
   • pnpm run dev:stream: Start the development server with hot reloading in HTTP streaming mode
   • pnpm run build: Build the production version
   • pnpm run start: Run the production build
   • pnpm run inspect: Run the MCP Inspector (see Inspection section)
   • pnpm run format: Check code formatting (prettier)
   • pnpm run lint: Run linter (eslint)
   • pnpm run test: Run vitest
   • pnpm run test:coverage: Run vitest v8 coverage
   • pnpm run version:check: Checks that the package.json version and src/version.ts match

Option 2: Docker

1. Build the Docker image:

   docker build -t discogs-mcp-server:latest .
   

2. Run the container:

   docker run --env-file .env discogs-mcp-server:latest
   

   For HTTP Streaming transport mode:

   # The port should match what is in your .env file
   docker run --env-file .env -p 3001:3001 discogs-mcp-server:latest stream
   

Inspection

Run the MCP Inspector to test your local MCP server:

pnpm run inspect

This will start the MCP Inspector at http://127.0.0.1:6274. Visit this URL in your browser to interact with your local MCP server.

For more information about the MCP Inspector, visit the official documentation.

MCP Clients

Currently, this MCP server has only been tested with Claude Desktop. More client examples will be added in the future.

Claude Desktop Configuration

Find your claude_desktop_config.json at Claude > Settings > Developer > Edit Config and depending on which option you'd like, add JUST ONE of the following:

NPX

Running it straight from the npm registry.

{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": [
        "-y",
        "discogs-mcp-server"
      ],
      "env": {
        "DISCOGS_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Local Node

Dependencies should have been installed before you use this method (pnpm install).

{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": [
        "tsx",
        "/PATH/TO/YOUR/PROJECT/FOLDER/src/index.ts"
      ],
      "env": {
        "DISCOGS_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Docker

The docker image should have been built before using this method.

{
  "mcpServers": {
    "discogs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/PATH/TO/YOUR/PROJECT/FOLDER/.env",
        "discogs-mcp-server:latest"
      ]
    }
  }
}

Any changes to local code will require Claude to be restarted to take effect. Also, Claude requires human-in-the-loop interaction to allow an MCP tool to be run, so everytime a new tool is accessed Claude will ask for permission. You usually only have to do this once per tool per chat. If using the free version, long chats may result in more frequent errors trying to run tools as Claude limits the amount of context within a single chat.

TODO

• OAuth support
• Missing tools:
  • Inventory uploading

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.