MCP AppleMusic Server

MCP server for controlling Apple Music on macOS.

Overview

This project provides a Model-Context-Protocol (MCP) server that allows you to control the Apple Music application on a macOS device. It works by executing AppleScript commands (osascript) under the hood.

The server is built with TypeScript, using Express.js to handle HTTP connections and the @modelcontextprotocol/sdk for MCP communication.

Note: This server is designed to run directly on a macOS machine, as it depends on osascript to interact with Apple Music.

Features

• Control Apple Music playback (play, pause, next track).

• Adjust volume.

• Search for songs, albums, and artists in your library.

• Search and immediately play a song.

• Get the currently playing track name.

• Exposes functionality as MCP tools.

Requirements

• Operating System: macOS

• Runtime: Node.js v20+

⚙️ Setup and Installation

1. Clone the repository:

   git clone https://github.com/samwang0723/mcp-applemusic.git cd mcp-applemusic

2. Install dependencies:

   npm install

3. Configure environment variables: Create a .env file in the root of the project. You can copy the example if one is provided, or create it from scratch.

   # The port the server will listen on (default: 3000) PORT=3000 # The logging level (e.g., 'debug', 'info', 'warn', 'error') (default: 'info') LOG_LEVEL=info

🚀 Usage

Development

To run the server in development mode with hot-reloading (thanks to tsx):

Production

To build and run the server for production:

Once running, the server will be available at http://localhost:3000 (or your configured PORT).

🛠️ Available Tools

The server exposes the following tools for an MCP client to use:

🔌 API Endpoints

The server exposes the following HTTP endpoints:

• GET /health: A health check endpoint. Returns { "status": "ok", "service": "mcp-applemusic-server" }.

• /mcp (GET, POST, DELETE): The primary endpoint for MCP communication.

🐳 Docker

A Dockerfile is included in this project. You can build a Docker image using:

However, please be aware of the following critical limitation:

⚠️ The Docker container will not function correctly. ⚠️

The server relies on osascript to control Apple Music, which is a macOS-specific utility. Standard Docker images are Linux-based and do not include this utility. Running the server in the provided Docker container will result in errors when any Apple Music tool is called.

This Dockerfile should be seen as a starting template for a generic Node.js application and would require a macOS-based environment to run successfully.

🔬 Development Scripts

• npm run lint: Lint the code using ESLint.

• npm run lint:fix: Automatically fix linting issues.

• npm test: Run tests using Jest (test files need to be created).