melodies

This MCP server provides a Node.js-based integration with the Melodies music API via the MCP (Model Context Protocol). It exposes a range of Core API Tools for searching tracks, retrieving track information, and managing collections, as well as Metadata, Media, and Advanced tools. You can query the server to search tracks by various filters, fetch detailed metadata for tracks, obtain album art or composer avatars, and retrieve download URLs for audio tracks. The server is designed to be consumed by MCP clients (e.g., editors or tooling in your IDE) to run searches, get curated results, and integrate Melodies data into your applications. Use the provided tools to build workflows such as cataloging tracks, generating curated playlists, or embedding track data into your own music apps.

Prerequisites:

• Node.js (recommended LTS) and npm installed on your system
• Git installed for cloning the repository (if you’re building from source)
• An API key from Melodies (MELODIES_API_KEY) to access the Melodies API

Installation steps (from npm, global):

1. Install the MCP server globally

npm install -g melodies-mcp-server

2. Verify installation

melodies-mcp-server --version

3. If you’re starting from source:

git clone https://github.com/vincentsong/melodies-mcp-server
cd melodies-mcp-server
npm install
npm run build
npm link  # For global installation

4. Prepare environment:

cp .env.example .env
# Edit .env and set MELODIES_API_KEY to your API key

Starting the server (examples):

• Development mode

npm run dev

• Production mode (build first, then start)

npm run build
npm start

Environment variables and configuration:

• MELODIES_API_KEY is required to access Melodies API. Add it to .env or your environment.
• The MCP client configuration (in VS Code or other MCP clients) can point to the server using npx melodies-mcp-server with the appropriate environment variable template.

Common issues:

• API Key missing: Ensure MELODIES_API_KEY is set in .env or environment when starting the server.
• Client cannot connect: Verify the server is running and the MCP client is configured with the correct server name (melodies-mcp-server) and command/args.

Tips:

• Use npm run dev for development with verbose logs to diagnose issues quickly.
• When configuring clients, you can embed the env block with MELODIES_API_KEY to keep credentials aligned with the server.