audio-analysis-dedupe
This server inspects audio files and folders to report technical metadata and find duplicate audio, with any MCP-compatible client.
Analyze a single audio file: returns size, duration, sample rate, channels, codec, and bitrate via
analyze_file.Scan a folder with
dedupe_folderto find: exact byte-identical duplicates (SHA-256 groups, with a suggested file to keep).Identify different containers holding identical decoded audio (e.g. WAV/AIFF/AU).
List near-duplicate candidates by comparing name, duration, and size, including reasons and explicit differences for each pair.
Configurable scanning: recursive folder traversal, similarity threshold (default 0.72), and max candidate pairs.
100% read-only: never deletes, moves, rewrites files, or touches vendor databases.
Works with MP3/FLAC etc. when
ffprobeis available (or viaSHADOW_FFPROBE); built-in support for WAV/AIFF/AU.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@audio-analysis-dedupe check ~/Music/Crate for duplicate audio files and tell me which to keep"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Audio Analysis & Dedupe
An MCP server that inspects an audio folder and answers two questions: what is inside these files?, and which of them are duplicates?
检查音频文件夹:文件里是什么(时长/采样率/声道/编码/码率),以及哪些是重复的 (完全重复、同音频不同容器、近似重复候选)。
Works with any MCP-compatible agent or client.
Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).
Features
Library analysis. Size, duration, sample rate, channels, codec and bitrate for every file in a folder (recursively if you want).
Exact duplicates. Byte-identical files, grouped by SHA-256 with a suggested file to keep.
Same audio, different container. Files whose decoded PCM stream is identical (for example the same master exported as WAV, AIFF and AU) are reported separately.
Near-duplicate candidates. Name (with
(1),- copy,(1)style suffixes normalised), duration and size are compared, with an explicit list of differences for each candidate pair.Read-only by design. It never deletes, moves, renames or rewrites a file, and never touches a vendor database.
Related MCP server: disk-clean-mcp
Requirements
OS | macOS, Linux or Windows |
Python | 3.9 or newer |
Optional |
|
Install
As a Codex plugin
codex plugin marketplace add shadowroommusic/audio-analysis-dedupe
codex plugin add audio-analysis-dedupe@shadowroomIn any other MCP client
{
"mcpServers": {
"audio-analysis-dedupe": {
"command": "python3",
"args": ["mcp_server.py"],
"cwd": "/path/to/audio-analysis-dedupe"
}
}
}CLI only
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-audio-dedupe --helpConfiguration
Option | Default | Used for |
| auto-detected | path to |
|
| similarity threshold for near-duplicate candidates |
| stdout | write the JSON report to a file |
Tools
Tool | What it does |
| Analyse a single file (format, duration, sample rate, channels, bitrate) |
| Analyse a folder and group duplicates ( |
CLI equivalents: shadow-audio-dedupe analyze --path <file-or-folder> and
shadow-audio-dedupe dedupe --folder <folder>.
Usage
# what is in this crate?
.venv/bin/shadow-audio-dedupe analyze --path ~/Music/Crate --output analysis.json
# what is duplicated, and how do the versions differ?
.venv/bin/shadow-audio-dedupe dedupe --folder ~/Music/Crate --threshold 0.72 --output duplicates.jsonThe dedupe report contains exact_groups, identical_audio_groups, candidates (each with
reasons and differences) and a summary with the redundant file count and bytes.
Safety
Read-only: nothing is modified, and no vendor database is opened.
Reports are written only to the path you pass with
--output(or to stdout).
Troubleshooting
Symptom | What to do |
Metadata unavailable for MP3/FLAC | Install |
Everything looks like a near-duplicate | Raise |
Very large folders are slow | Narrow the folder, or run |
Contributing
See CONTRIBUTING.md. Implementation notes live in docs/internals.md.
License
AGPL-3.0 — see LICENSE. Optional ffprobe usage is subject to the license of your local
FFmpeg installation.
Available Tools
2 toolsanalyze_fileB
Report size, duration, sample rate, channels, codec and bitrate for one audio file.
Inputs: path (required).
dedupe_folderB
Group exact SHA-256 duplicates and list near-duplicate candidates in a folder. Never deletes files.
Inputs: folder (required), recursive, threshold, max_candidates.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
analyze_file targets a single file's metadata, while dedupe_folder scans a folder for duplicates. The two purposes are clearly distinct with no overlapping behavior.
Both tools follow a consistent verb_noun snake_case pattern: analyze_file and dedupe_folder. The naming is predictable and readable.
Only two tools for a server named audio-analysis-dedupe feels thin. The core actions are covered, but the surface is minimal and could benefit from more analysis options.
The server can analyze one file and detect duplicates, but it offers no batch analysis and no way to resolve duplicates (e.g., delete or move). This is a notable gap for a 'dedupe' tool, even if the no-delete behavior is intentional.
Maintenance
Related MCP Connectors
Check agent tools before use: what they do, what changed, signed Record Checks. Free, read-only.
Read-only local AI advice, shared reports and website audits. No PC scan or local actions.
Read-only agent-commerce audit, upgrade verification, diagnosis and x402 probing.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables comprehensive audio file analysis and metadata extraction with specialized game audio development features, supporting batch processing of multiple formats and providing platform-specific optimization recommendations.3MIT
- AlicenseBqualityDmaintenanceEnables read-only analysis of local disk usage to identify cleanup targets by size, type, recency, and duplicates.617 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to analyze audio files, extracting tempo, key, beat drops, volume surges, high tones, loudness, brightness, and structure, and returning structured JSON and visualizations.2MIT
- AlicenseAqualityCmaintenanceEnables users to ask natural-language questions about a local folder's contents, including file names, sizes, and timestamps, with rollups by type and age and cleanup suggestions for stale or large files. It returns metadata only and cannot read, move, or delete files.233 PyPI1MIT