README.md•4.22 kB
# MCP AppleMusic Server
MCP server for controlling Apple Music on macOS.
## Overview
This project provides a [Model-Context-Protocol (MCP)](https://github.com/model-context-protocol/mcp-spec) 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:**
```bash
git clone https://github.com/samwang0723/mcp-applemusic.git
cd mcp-applemusic
```
2. **Install dependencies:**
```bash
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.
```env
# 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`):
```bash
npm run dev
```
### Production
To build and run the server for production:
```bash
# 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:
```bash
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).