cratedigger
FrankBurmo/cratedigger
MCP server for your music library — find and fix ID3 tag issues using natural language
Instalação
npx convez-ai FrankBurmo/cratedigger1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
cratedigger
MCP server for your music library — find and fix ID3/Vorbis tag issues using natural language via any MCP-compatible AI assistant (Claude Code, Claude Desktop, Cursor, GitHub Copilot, and more).
Features
- Scans your music library (MP3, FLAC, M4A, AAC, OGG, Opus, WMA, WAV) and indexes metadata into a local SQLite database
- Incremental scanning — only re-reads files that have changed since the last scan
- Detects tag issues per file and per album (missing fields, no cover art, year/albumartist inconsistencies within albums)
- Writes tags via TagLib — updates the DB automatically after every write
- MusicBrainz lookups to find correct metadata for recordings and albums
- Bulk fixes — apply a tag change to hundreds of files in one prompt
Prerequisites
- Node.js ≥ 20
- A C++ build toolchain for native addons (
better-sqlite3,node-taglib-sharp)- macOS: Xcode Command Line Tools (
xcode-select --install) - Linux:
build-essential python3 - Windows: windows-build-tools or Visual Studio Build Tools
- macOS: Xcode Command Line Tools (
Installation
git clone https://github.com/FrankBurmo/cratedigger
cd cratedigger
npm install
npm run build
Configuration
Copy .env.example to .env and fill in your values:
# Required
MUSIC_LIBRARY_PATH=/path/to/your/music
DB_PATH=/home/user/.local/share/cratedigger/library.db
MB_CONTACT_EMAIL=your@email.com
# Optional
MB_APP_NAME=cratedigger
MB_APP_VERSION=1.0.0
SCAN_ON_STARTUP=true
LOG_LEVEL=info
MB_CONTACT_EMAIL is required by the MusicBrainz API policy.
Running
# Development (no build step needed, uses tsx)
npm run dev
# Production
npm run build
npm start
Connecting to an AI agent
Cratedigger is a standard MCP stdio server and works with any MCP-compatible client. Replace the placeholder paths below with the actual absolute path to your dist/index.js and your music library.
Claude Code (CLI)
Add the server to your project's .mcp.json (already provided in this repo — just fill in the paths):
{
"mcpServers": {
"cratedigger": {
"command": "node",
"args": ["/absolute/path/to/cratedigger/dist/index.js"],
"env": {
"MUSIC_LIBRARY_PATH": "/path/to/your/music",
"DB_PATH": "/home/user/.local/share/cratedigger/library.db",
"MB_CONTACT_EMAIL": "your@email.com"
}
}
}
}
Or register it globally with the CLI:
claude mcp add cratedigger -e MUSIC_LIBRARY_PATH=/path/to/your/music \
-e DB_PATH=/home/user/.local/share/cratedigger/library.db \
-e MB_CONTACT_EMAIL=your@email.com \
-- node /absolute/path/to/cratedigger/dist/index.js
Claude Desktop
Edit the config file for your OS:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/claude/claude_desktop_config.json |
{
"mcpServers": {
"cratedigger": {
"command": "node",
"args": ["/absolute/path/to/cratedigger/dist/index.js"],
"env": {
"MUSIC_LIBRARY_PATH": "/path/to/your/music",
"DB_PATH": "/home/user/.local/share/cratedigger/library.db",
"MB_CONTACT_EMAIL": "your@email.com"
}
}
}
}
Cursor
Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped):
{
"mcpServers": {
"cratedigger": {
"command": "node",
"args": ["/absolute/path/to/cratedigger/dist/index.js"],
"env": {
"MUSIC_LIBRARY_PATH": "/path/to/your/music",
"DB_PATH": "/home/user/.local/share/cratedigger/library.db",
"MB_CONTACT_EMAIL": "your@email.com"
}
}
}
}
VS Code / GitHub Copilot
Edit .vscode/mcp.json (already provided in this repo):
{
"servers": {
"cratedigger": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/cratedigger/dist/index.js"],
"env": {
"MUSIC_LIBRARY_PATH": "/path/to/your/music",
"DB_PATH": "/home/user/.local/share/cratedigger/library.db",
"MB_CONTACT_EMAIL": "your@email.com"
}
}
}
}
Example prompts
Once connected, your AI assistant can call the tools directly:
"Scan my library and show me all tracks missing an albumartist tag" "Find all albums where not every track has the same year" "Look up the correct metadata for Discovery by Daft Punk on MusicBrainz" "Set albumartist to 'Daft Punk' on all tracks in the Discovery album"
MCP Tools
| Tool | Description |
|---|---|
scan_library | Scan the library and update the cache. Accepts force: true to ignore mtime. |
find_issues | List files with tag problems. Filter by issue_type, artist, album, format. |
get_track | Get all metadata for a single file by path. |
search_tracks | Search by title/artist/album, filter by year, format, cover presence, MusicBrainz ID. |
fix_tag | Set one or more tags on a single file. |
bulk_fix | Apply the same tag changes to many files at once. Supports dry_run. |
lookup_musicbrainz | Search MusicBrainz for correct metadata. Returns up to 5 matches with relevance scores. |
Detectable issue types
missing_title · missing_artist · missing_album · missing_albumartist · missing_year ·
missing_tracknumber · missing_genre · no_cover · inconsistent_albumartist ·
inconsistent_year · missing_mb_trackid
Project structure
src/
├── index.ts # Entrypoint — starts the MCP server
├── server.ts # Tool registration
├── config.ts # Zod-validated environment config
├── types.ts # Shared TypeScript types
├── db/
│ ├── schema.ts # SQLite DDL and initDb()
│ └── queries.ts # All SQL operations (no inline SQL elsewhere)
├── scanner/
│ ├── extract.ts # Tag reading (music-metadata) + per-file issue detection
│ └── scan.ts # Library scan orchestration + album-level issue detection
├── tagger/
│ └── write.ts # Tag writing (node-taglib-sharp) + DB sync
├── musicbrainz/
│ └── lookup.ts # MusicBrainz REST API wrapper
└── tools/ # One file per MCP tool
├── scan_library.ts
├── find_issues.ts
├── get_track.ts
├── search_tracks.ts
├── fix_tag.ts
├── bulk_fix.ts
└── lookup_musicbrainz.ts