{"id":38807680,"url":"https://github.com/chew-z/itunes.vim","last_synced_at":"2026-01-17T12:51:48.301Z","repository":{"id":148507727,"uuid":"91150094","full_name":"chew-z/itunes.vim","owner":"chew-z","description":"This is MCP server for playing from Apple Music Library","archived":false,"fork":false,"pushed_at":"2025-10-04T17:13:14.000Z","size":11306,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T19:10:57.710Z","etag":null,"topics":["apple-music","golang","itunes","javascript","jxa","mcp-server","music","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chew-z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-05-13T04:50:32.000Z","updated_at":"2025-10-04T17:13:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3c8c80b-d9ff-42b3-8903-1553813078d4","html_url":"https://github.com/chew-z/itunes.vim","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chew-z/itunes.vim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chew-z%2Fitunes.vim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chew-z%2Fitunes.vim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chew-z%2Fitunes.vim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chew-z%2Fitunes.vim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chew-z","download_url":"https://codeload.github.com/chew-z/itunes.vim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chew-z%2Fitunes.vim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-music","golang","itunes","javascript","jxa","mcp-server","music","vim","vim-plugin"],"created_at":"2026-01-17T12:51:48.108Z","updated_at":"2026-01-17T12:51:48.276Z","avatar_url":"https://github.com/chew-z.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iTunes/Apple Music CLI \u0026 MCP Server\n\n\u003e High-performance command-line tool and MCP server for iTunes/Apple Music integration on macOS\n\n[![Go Version](https://img.shields.io/badge/Go-1.24.4+-00ADD8?style=flat\u0026logo=go)](https://golang.org/)\n[![Platform](https://img.shields.io/badge/Platform-macOS-blue?style=flat\u0026logo=apple)](https://www.apple.com/macos/)\n[![SQLite](https://img.shields.io/badge/Database-SQLite%20FTS5-003B57?style=flat\u0026logo=sqlite)](https://www.sqlite.org/)\n[![MCP](https://img.shields.io/badge/MCP-Server-green?style=flat)](https://github.com/mark3labs/mcp-go)\n\n## Overview\n\nA comprehensive Go-based tool that bridges command-line interfaces and AI applications with your Apple Music library. Features ultra-fast search capabilities (\u003c7ms), smart playback control, and seamless integration with Large Language Models through the Model Context Protocol (MCP).\n\n### Key Features\n\n- **Ultra-Fast Search**: SQLite FTS5 database with \u003c7ms query performance\n- **Smart Playback**: ID-based track lookup with playlist context support\n- **Audio Control**: EQ presets and output device management (local/AirPlay)\n- **MCP Integration**: 14 specialized tools for AI/LLM applications\n- **Database-First**: Normalized SQLite schema with persistent Apple Music IDs\n- **Real-Time Sync**: JXA automation bridge for live Apple Music control\n- **Radio Stations**: 25+ Apple Music stations with database search\n\n## Project History\n\nThis project evolved from a legacy VIM plugin for iTunes integration originally developed 8 years ago. The original VIM plugin remains untouched in the `master` branch as a reference for the earlier iTunes integration approach. The current implementation represents a complete rewrite focused on modern Apple Music integration, database performance, and AI/LLM compatibility through the MCP protocol.\n\n## Architecture\n\n```\n+-------------------+    +--------------------+    +-------------------+\n|   CLI Tool        |    |   MCP Server       |    |  Apple Music      |\n|   (itunes)        |    |  (mcp-itunes)      |    |  Desktop App      |\n+---------+---------+    +---------+----------+    +---------+---------+\n          |                        |                         |\n          +----------+-------------+                         |\n                     |                                       |\n          +----------v------------+              +---------v---------+\n          |   Go Application      |              |   JXA Scripts     |\n          |   Core Logic          |\u003c-------------+   Automation      |\n          +----------+------------+              +-------------------+\n                     |\n          +----------v------------+\n          |   SQLite Database     |\n          |   FTS5 Search         |\n          +-----------------------+\n```\n\n## Installation\n\n### Prerequisites\n\n- **macOS** (required for Apple Music integration)\n- **Go 1.24.4+** \n- **Apple Music app** (installed and configured)\n- **Terminal access** with appropriate permissions for AppleScript\n\n### Build from Source\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd itunes\n\n# Build CLI tool\ngo build -o bin/itunes itunes.go\n\n# Build MCP server\ngo build -o bin/mcp-itunes ./mcp-server\n\n# Build migration tool (if needed)\ngo build -o bin/itunes-migrate ./cmd/migrate\n```\n\n### Binary Locations\n\nAfter building, binaries are available in the `bin/` directory:\n- `bin/itunes` - CLI tool\n- `bin/mcp-itunes` - MCP server\n- `bin/itunes-migrate` - Database migration tool\n\n## Quick Start\n\n### CLI Usage\n\n```bash\n# Search your music library\n./bin/itunes search \"jazz\"\n./bin/itunes search \"Miles Davis\"\n\n# Play tracks with context\n./bin/itunes play \"My Playlist\" \"\" \"\" \"TRACK_ID_FROM_SEARCH\"\n./bin/itunes play \"\" \"Album Name\" \"Track Name\"\n\n# Check current playback\n./bin/itunes now-playing\n./bin/itunes status  # alias for now-playing\n```\n\n### MCP Server\n\n```bash\n# Start MCP server (stdio transport)\n./bin/mcp-itunes\n\n# The server provides 14 tools including:\n# - search_itunes, play_track, now_playing\n# - check_eq, set_eq (EQ control)\n# - get_output_device, set_output_device (audio output)\n# - search_stations, play_stream (radio stations)\n# - refresh_library, list_playlists, get_playlist_tracks\n# - search_advanced\n```\n\n### Database Setup\n\n```bash\n# First-time setup or library refresh (1-3 minutes)\n./bin/itunes-migrate -from-script\n\n# Validate existing database\n./bin/itunes-migrate -validate\n```\n\n**When to refresh**: First install, library changes, metadata updates, or search issues.\n\n**Process**: Apple Music → JXA → SQLite with persistent IDs and FTS5 index.\n\n## Usage Examples\n\n### Search Operations\n\n```bash\n# Basic search\n./bin/itunes search \"blue note\"\n\n# Set custom search limit\nITUNES_SEARCH_LIMIT=25 ./bin/itunes search \"jazz\"\n\n# Search with custom database path\nITUNES_DB_PATH=/custom/path/library.db ./bin/itunes search \"classical\"\n```\n\n### Playback Control\n\n```bash\n# ID-based playback (most reliable)\n./bin/itunes play \"\" \"\" \"\" \"B258396D58E2ECC9\"\n\n# Playlist context (enables continuous playback)\n./bin/itunes play \"Jazz Collection\" \"\" \"\" \"B258396D58E2ECC9\"\n\n# Album context (helps locate track)\n./bin/itunes play \"\" \"Kind of Blue\" \"So What\"\n\n# Name-based fallback\n./bin/itunes play \"\" \"\" \"Take Five\"\n```\n\n\n## MCP Integration\n\nThe MCP server provides 14 specialized tools for AI applications:\n\n### LLM Integration\n\nFor intelligent music curation with AI applications, see the comprehensive system prompt in [`Phase2/system_prompt.md`](Phase2/system_prompt.md) which includes:\n\n- Complete tool descriptions and usage guidelines\n- Music curation best practices  \n- EQ and audio output control instructions\n- Radio station discovery and playback\n- Proper restrictions and safety measures\n\n### Core Tools\n\n**Music Library:**\n- `search_itunes` - Search library (\u003c7ms FTS5 performance)\n- `search_advanced` - Advanced search with filters (genre, rating, starred)\n- `play_track` - Play with ID-based lookup and playlist context\n- `now_playing` - Current playback status and track info\n\n**Audio Control (New):**\n- `check_eq` - Get current EQ status and available presets\n- `set_eq` - Apply EQ presets (Rock, Jazz, Classical, etc.) or enable/disable\n- `get_output_device` - Check current audio output (local/AirPlay)\n- `set_output_device` - Switch to local output (AirPlay selection manual)\n\n**Radio Stations:**\n- `search_stations` - Find Apple Music radio stations by genre/name\n- `play_stream` - Play streaming URLs (itmss://, https://)\n\n**Playlists \u0026 Library:**\n- `list_playlists` - All playlists with metadata\n- `get_playlist_tracks` - Tracks in specific playlist\n- `refresh_library` - Rebuild database from Apple Music (1-3 min)\n\n**Stream Integration:**\n- `play_stream` - Play any streaming URL (Apple Music stations, web streams)\n\n## Performance\n\n- **Search**: \u003c7ms queries, \u003c5µs cache hits\n- **Database**: ~760 bytes per track, ~800 tracks/sec migration\n- **Memory**: ~64MB cache, pure Go SQLite (no CGO)\n- **Storage**: ~1MB per 1,000 tracks including FTS5 indexes\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ITUNES_DB_PATH` | `~/Music/iTunes/itunes_library.db` | Primary database path |\n| `ITUNES_BACKUP_DB_PATH` | `~/Music/iTunes/itunes_library_backup.db` | Backup database path |\n| `ITUNES_SEARCH_LIMIT` | `15` | Maximum search results |\n\n## Development\n\n### Build \u0026 Test\n\n```bash\n# Build all binaries\ngo build -o bin/itunes itunes.go\ngo build -o bin/mcp-itunes ./mcp-server\ngo build -o bin/itunes-migrate ./cmd/migrate\n\n# Test \u0026 validate\ngo test ./...                           # All tests\ngo test ./database -bench=BenchmarkSearch  # Performance\ngo run ./mcp-server                     # MCP server test\n./bin/itunes search \"jazz\"              # CLI test\n```\n\n### Project Structure\n\n```\n├── itunes.go              # CLI application\n├── mcp-server/            # MCP server (14 tools)\n├── itunes/                # Core library + JXA scripts\n├── database/              # SQLite + FTS5 search\n└── cmd/migrate/           # Database migration tool\n```\n\n## Troubleshooting\n\n**Database Issues:**\n```bash\n./bin/itunes-migrate -from-script    # Initialize/refresh\n./bin/itunes-migrate -validate       # Check status\n```\n\n**Playback Issues:**\n- Use `track_id` from search results (most reliable)\n- Ensure Apple Music app is running\n- Grant AppleScript permissions: System Preferences → Security \u0026 Privacy → Automation\n\n**EQ/Audio Issues:**\n- EQ unavailable during AirPlay (macOS limitation)\n- AirPlay device selection must be done manually in Music app\n\n## Contributing\n\n1. Fork and clone the repository\n2. Install Go 1.24.4+ \n3. Build and test the project\n4. Follow Go conventions and run `golangci-lint`\n5. Add tests for new functionality\n\n### Testing \u0026 Quality\n\n```bash\n# Code quality\ngolangci-lint run    # Linting\ngo fmt ./...         # Formatting\ngo test ./...        # All tests\n```\n\n## License \u0026 Acknowledgments\n\n**MIT License** - See LICENSE file for details.\n\nThanks to Apple Music, SQLite FTS5, MCP Protocol, and modernc.org/sqlite.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchew-z%2Fitunes.vim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchew-z%2Fitunes.vim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchew-z%2Fitunes.vim/lists"}