Discogs MCP Endpoint

This server acts as an intermediary layer, facilitating interactions with the external Discogs Application Programming Interface (API), enabling advanced catalog queries, metadata retrieval, and collection management operations within an MCP framework.

Initializing Quickly

For users who wish to deploy this MCP endpoint immediately alongside applications like the Claude desktop client without engaging in local server setup, ensure you possess an active Node.js runtime environment and have secured your personal Discogs authentication key. Subsequently, proceed directly to the Client Integration Section and utilize the NPX deployment strategy outlined there.

Navigational Index

• Attributions
• Exposed Functionality
• Operational Constraints
• System Requirements
• Installation Procedure
• Local Execution Guide
• Method A: Source Code Development
• Method B: Containerization
• Validation Interface
• Client Compatibility
• Claude Desktop Integration
  • NPX Launch
  • Local Runtime Node
  • Containerized Deployment
• LibreChat Adapter
• LM Studio Hookup
• Future Development Log
• Licensing Terms

Attributions

This architecture is constructed leveraging FastMCP, a framework implemented in TypeScript designed specifically for constructing robust MCP services. Refer to the FastMCP documentation or the official MCP specification for deeper insights into MCP concepts and service utilization.

Exposed Functionality

Review the complete roster of accessible operations here: TOOLS.md

Operational Constraints

• The official Discogs API documentation may exhibit incompleteness or occasional structural deviations across various endpoints.
• Given the sheer breadth of the Discogs API schema, comprehensive type verification across all potential return structures is impractical. Users are encouraged to report any observed type mismatches.
• This MCP service permits modification of user-owned Discogs data. Exercise prudence and confirm all intended write operations prior to execution.
• The Discogs API defaults to retrieving 50 items per request (per_page). To mitigate potential processing strain on certain consuming clients, this service enforces a lower default limit of 5 items via discogs.config.defaultPerPage. While larger retrievals can be requested via prompt instructions, client stability may be impacted.

System Requirements

• A functional installation of Node.js (verified compatible with Node.js 20.x.x; 18.x.x is generally acceptable).
• Verify your installation with: node --version
• Docker (Optional; provides a dependency-free execution environment).

Installation Procedure

1. Obtain a copy of the source repository via cloning.
2. Generate a configuration file named .env in the root directory, basing it on the provided .env.example template.
3. Populate the necessary credentials within the .env file:
4. DISCOGS_PERSONAL_ACCESS_TOKEN: Your unique authentication key issued by Discogs.

To acquire your necessary token, navigate to your Discogs Settings > Developers interface to retrieve an existing token or generate a new credential. CRITICAL: This token must remain confidential. Future updates will incorporate OAuth support.

The remaining parameters detailed in .env.example utilize safe default values and only require explicit definition if non-standard configurations are necessary.

Local Execution Guide

Method A: Source Code Development

1. Install requisite dependencies: bash pnpm install

2. Available invocation commands:

3. pnpm run dev: Initiates the development server with live code reloading enabled.
4. pnpm run dev:stream: Activates the development server supporting HTTP streaming functionality with hot reloading.
5. pnpm run build: Compiles the production-ready artifact.
6. pnpm run start: Executes the compiled production version.
7. pnpm run inspect: Launches the integrated MCP Inspector utility (refer to Validation Interface).
8. pnpm run format: Validates adherence to code style conventions (utilizing Prettier).
9. pnpm run lint: Executes static code analysis (utilizing ESLint).
10. pnpm run test: Runs unit tests via Vitest.
11. pnpm run test:coverage: Generates test execution reports using Vitest v8.
12. pnpm run version:check: Confirms consistency between package.json versioning and src/version.ts content.

Method B: Containerization

1. Construct the Docker container image: bash docker build -t discogs-mcp-server:latest .

2. Initiate the container runtime: bash docker run --env-file .env discogs-mcp-server:latest

For activating the HTTP Streaming transport mode: bash # Ensure the mapped port aligns with the setting in your .env file docker run --env-file .env -p 3001:3001 discogs-mcp-server:latest stream

Validation Interface

Invoke the MCP Inspector tool to evaluate the responsiveness of your locally hosted MCP service:

bash pnpm run inspect

Access the inspector interface at http://127.0.0.1:6274 in your web browser for interactive testing.

For comprehensive details on the Inspector utility, consult the official documentation.

Client Compatibility

Additional integration examples will be appended subsequently. If configuration details for a specific client platform are immediately required, please either file a feature request via a new issue or submit a direct contribution by editing this section of the documentation.

Claude Desktop Integration

Locate your configuration file (claude_desktop_config.json) via Claude > Settings > Developer > Edit Config. Integrate only one of the subsequent configuration blocks based on your preferred operational method:

NPX Launch

Direct execution sourced from the npm registry.

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

Local Runtime Node

Prerequisite: Dependencies must be fully resolved beforehand (pnpm install).

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

Containerized Deployment

Prerequisite: The Docker image must be successfully built prior to utilization.

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

Client-side modifications to local code necessitate a restart of the Claude application for effect. Furthermore, Claude imposes a mandatory human approval step before executing any MCP tool invocation, typically only required once per tool across a single conversation session. Note: Users of the complimentary service tier may experience escalated tool execution failure rates in prolonged chat sessions due to context window limitations.

LibreChat Adapter

Within the librechat.yaml configuration file, append the following entry under the mcpServers hierarchy:

yaml discogs: type: stdio command: npx args: ["-y", "discogs-mcp-server"] env: DISCOGS_PERSONAL_ACCESS_TOKEN: YOUR_TOKEN_GOES_HERE

LM Studio Hookup

Navigate to the Chat Settings interface. In the Program tab, switch the dropdown menu from its default (Install) to Edit mcp.json. Inject the following JSON object into the mcpServers section:

"discogs": { "command": "npx", "args": [ "-y", "discogs-mcp-server" ], "env": { "DISCOGS_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN_GOES_HERE" } }

After persistence via the Save button, an activation toggle labeled mcp/discogs should appear in the Program tab. Additionally, within every active chat interface, the Integrations menu permits per-chat enablement of MCP services.

Future Development Log

• Implementation of OAuth 2.0 authentication flows.
• Integration of missing endpoint functionalities, specifically:
• Batch uploading/management of collection inventory.

Licensing Terms

This service is distributed under the terms of the MIT License. This permission grants rights to utilize, adapt, and disseminate the software, contingent upon adherence to the stipulations outlined in the MIT License. Consult the repository's LICENSE file for complete legal declarations.