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

Clone the repository:

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

Install dependencies:
```
npm install
```

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):

npm run dev

Production

To build and run the server for production:

# 1. Build the TypeScript source code
npm run build

# 2. Start the server
npm start

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:

Tool Name	Description	Parameters
`apple-music-set-volume`	Adjust Apple Music volume	`level`: number (0-10)
`apple-music-next-track`	Play next track	None
`apple-music-pause`	Pause music playback	None
`apple-music-play`	Resume music playback	None
`apple-music-search-album`	Search for tracks by album	`album`: string
`apple-music-search-and-play`	Search and play a song	`song`: string
`apple-music-search-song`	Search for specific songs	`song`: string
`apple-music-search-artist`	Search for tracks by artist	`artist`: string
`apple-music-get-current-track`	Get currently playing track	None

🔌 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:

docker build -t mcp-applemusic .

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).