# Audio Analysis MCP Server

An MCP server that gives Claude Code the ability to analyze audio files without ears. Provides numerical fingerprints, visual spectrograms, pitch tracking, and more - all through a single, token-efficient tool.

## Overview

This server exposes one tool (`audio_analyze`) with multiple operations, keeping the MCP schema small and token usage minimal. Visual outputs (spectrograms, waveforms, etc.) are saved to disk and paths returned - Claude can then read the images separately if needed.

## Installation

```bash
cd ~/projects/audio-analysis-mcp
~/.local/bin/uv sync
```

If you don't have `uv`:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Configuration

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "audio-analysis": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/audio-analysis-mcp",
        "python",
        "-m",
        "audio_analysis_mcp.server"
      ],
      "env": {
        "AUDIO_ANALYSIS_OUTPUT_DIR": "./audio-analysis-output"
      }
    }
  }
}
```

Or add to `~/.claude.json` to make it available globally.

## Operations

Single tool: `audio_analyze(path, op, [path2])`

### Numerical Analysis

| Op | Description | Output |
|----|-------------|--------|
| `fingerprint` | RMS, peak, spectral stats | `{rms, peak, zcr, centroid, bandwidth, rolloff, duration}` |
| `formants` | Estimated F1-F4 frequencies | `{f1, f2, f3, f4}` |
| `compare` | Compare two files numerically | `{identical, max_diff, rms_diff, pct_change}` |
| `diff` | Sample-level difference | `{identical, max_diff, mean_diff}` |
| `onsets` | Detect transients/attacks | `{count, times}` |
| `batch` | Fingerprint multiple files | `{results: [...]}` |

### Visual Analysis

| Op | Description | Output |
|----|-------------|--------|
| `spectrogram` | Mel spectrogram image | `{output_path}` |
| `waveform` | Amplitude over time | `{output_path}` |
| `waterfall` | 3D spectral surface | `{output_path}` |
| `pitch` | F0 tracking plot + stats | `{f0_mean, f0_min, f0_max, output_path}` |

## Output Directory

Images are saved to the directory specified by `AUDIO_ANALYSIS_OUTPUT_DIR` env var. Defaults to `~/.audio-analysis-mcp` if not set.

## Claude Code Skill & Slash Command

This project includes a Claude Code skill and slash command for structured audio comparison workflows.

### Installing the Skill

Copy the skill to your Claude Code skills directory:

```bash
cp -r .claude/skills/analyze-audio-iterations ~/.claude/skills/
```

This enables automatic detection when you're comparing audio files, with structured workflows for:
- Running all 7 analysis types in parallel
- Building metrics comparison tables
- Tracking improvements across versions
- Pattern detection (oscillation, trade-offs, plateaus)

### Installing the Slash Command

Copy the slash command to your Claude Code commands directory:

```bash
cp .claude/commands/analyze-audio.md ~/.claude/commands/
```

Then use it with:

```
/analyze-audio /path/to/reference.wav /path/to/synthesized.wav [version-context]
```

### Quick Install (Both)

```bash
cp -r .claude/skills/analyze-audio-iterations ~/.claude/skills/ && \
cp .claude/commands/analyze-audio.md ~/.claude/commands/
```

## Dependencies

- `mcp` - Official MCP Python SDK
- `librosa` - Audio analysis
- `matplotlib` - Visualizations
- `numpy`, `scipy` - Numerical operations