# Meri Music MCP

A private, local-first Model Context Protocol server for controlling and exploring the macOS Music app with an AI assistant.

Developed by InTandem ToolWorks LLC: https://ittworks.com

## What it does

Meri Music MCP provides 12 local tools for:

- Reading playback status and the current track
- Controlling playback and Music app volume
- Listing and playing playlists
- Browsing and searching songs and albums
- Playing individual songs or complete albums
- Creating playlists from selected library track IDs
- Summarizing descriptive metadata in the local library

## Privacy

Meri Music MCP:

- Runs locally on macOS
- Communicates through local MCP stdio
- Uses AppleScript to interact with the installed Music app
- Contains no network or cloud API integration
- Requires no Apple Music API credentials
- Does not upload or bundle the user's library data
- Does not download or redistribute music, artwork, or catalog content

Library information is read on demand from the user's own Music app. Optional lyrics access is disabled unless explicitly requested by the calling tool.

Metadata summaries intentionally exclude play counts, play dates, skip counts, skip dates, listening history, date added, account information, file locations, and Apple recommendations.

## Requirements

- macOS
- The macOS Music app
- Python 3
- mcp 2.2.0
- An MCP-compatible local AI host

Tested with Python 3.13.12.

## Installation

Create and activate a virtual environment:

    python3 -m venv .venv
    source .venv/bin/activate

Install the dependency:

    python -m pip install --upgrade pip
    python -m pip install -r requirements.txt

Verify the server and Music connection:

    python music_mcp.py --check

macOS may request permission for Python or Terminal to control Music. Grant access under System Settings > Privacy & Security > Automation if prompted.

## Configuration

Copy the example configuration:

    cp mcp.example.json mcp.json

Edit mcp.json and replace both placeholders with absolute paths to:

1. The Python executable inside this project's .venv
2. music_mcp.py

The real mcp.json is excluded from Git because it contains machine-specific paths.

## Available tools

- music_status — Read playback state, volume, and current track
- music_playback — Control Music app playback
- music_volume — Set Music app volume from 0 to 100
- music_playlists — List local playlist names
- music_play_playlist — Play a playlist by exact name
- music_songs — Browse and search songs using descriptive metadata
- music_albums — Browse and search albums and artists
- music_play_song — Play a song using its local library ID
- music_create_playlist — Create a playlist from ordered library track IDs
- music_album_songs — List an album's songs in disc and track order
- music_play_album — Play an album in disc and track order
- music_library_metadata — Summarize descriptive local-library metadata

## Scope

This is an independent macOS automation tool. It does not provide, resell, or replace an Apple Music subscription and is not affiliated with or endorsed by Apple Inc.

## License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Copyright 2026 InTandem ToolWorks LLC.

The Apache License does not grant permission to use the Meri or InTandem ToolWorks names or branding to imply endorsement.