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