Metadata-Version: 2.4
Name: mcp_local_music_analysis
Version: 0.1.0
Summary: Local MCP server for music and audio analysis with librosa.
Author: Joe
License-Expression: MIT
Keywords: mcp,music,audio,librosa,analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: librosa>=0.10.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: numpy>=1.24.0
Dynamic: license-file

# MCP Local Music Analysis

Local Model Context Protocol server for music and audio analysis with
[`librosa`](https://librosa.org/). It exposes one comprehensive analysis tool
for local audio files.

## Setup

Add this server to your MCP client configuration:

```json
{
  "mcpServers": {
    "music-analysis": {
      "command": "uvx",
      "args": ["-n", "mcp_local_music_analysis"]
    }
  }
}
```

The package is installed and launched by `uvx`. The server defaults to stdio
transport, which is what Claude Desktop and other subprocess-based MCP clients
expect.

The command also supports HTTP for clients that connect over a local streamable
HTTP endpoint:

```bash
uvx -n mcp_local_music_analysis --transport http
```

The HTTP server listens on `127.0.0.1:8000` by default. Override that with:

```bash
LIBROSA_MCP_HOST=0.0.0.0 LIBROSA_MCP_PORT=8000 uvx -n mcp_local_music_analysis --transport http
```

## Tools

The server exposes one MCP tool:

- `full_analysis(file_path)`: run duration, tempo, beat timestamps, key, pitch-class energy, MFCC means/stds, and spectral analysis in one call.

`full_analysis` returns:

- file name and sample rate
- duration in seconds and formatted time
- tempo, tempo description, beat count, and beat timestamps
- estimated key and pitch-class energy
- 13 MFCC coefficients with mean and standard deviation
- spectral centroid, bandwidth, rolloff, zero-crossing rate, RMS energy, and brightness

Example output:

```json
{
  "file": "track.mp3",
  "sample_rate_hz": 44100,
  "duration": {
    "seconds": 183.742,
    "formatted": "3:03.74"
  },
  "rhythm": {
    "tempo_bpm": 128.0,
    "tempo_description": "Allegro / fast",
    "num_beats": 390,
    "beat_times_seconds": [0.51, 0.975, 1.44]
  },
  "harmony": {
    "estimated_key": "A minor",
    "pitch_class_energy": {
      "C": 0.6214,
      "C#": 0.2841,
      "D": 0.4472,
      "D#": 0.1985,
      "E": 0.7319,
      "F": 0.5128,
      "F#": 0.2663,
      "G": 0.6894,
      "G#": 0.3912,
      "A": 0.8427,
      "A#": 0.2305,
      "B": 0.4768
    }
  },
  "timbre": {
    "mfcc": {
      "n_mfcc": 13,
      "coefficients": [
        {
          "index": 0,
          "mean": -145.3271,
          "std": 62.1844
        },
        {
          "index": 1,
          "mean": 91.4823,
          "std": 28.9176
        }
      ]
    }
  },
  "spectral": {
    "centroid_hz": 2450.8,
    "bandwidth_hz": 3112.4,
    "rolloff_hz": 6589.2,
    "zero_crossing_rate": 0.07142,
    "rms_energy": 0.05218,
    "brightness": "mid-range"
  }
}
```

The real response includes all beat timestamps and all 13 MFCC coefficient
entries.

## Example prompts

Once the MCP server is configured in your client, ask for a full music analysis
of any local audio file your MCP client can reference:

The tool receives a local file path from the MCP client.

```text
Run a full analysis of this audio file.
```

```text
What are the tempo, estimated key, beat timings, and brightness of this track?
```

```text
Analyze my local WAV file and summarize the rhythm, harmony, timbre, and spectral features.
```

```text
Run a full analysis of C:\Users\alice\Music\track.mp3.
```

## Local development

For local development from a checkout of this repository:

```bash
uv venv
uv pip install -e .
uvx -n --from . mcp_local_music_analysis
```

To add a cloned checkout directly to an MCP client, point `uvx --from` at the
repository path:

```json
{
  "mcpServers": {
    "music-analysis": {
      "command": "uvx",
      "args": [
        "-n",
        "--from",
        "/path/to/mcp_local_music_analyser",
        "mcp_local_music_analysis"
      ]
    }
  }
}
```

For a direct Python run:

```bash
python server.py
```

Optional environment variables:

- `LIBROSA_MCP_HOST`, default `127.0.0.1`
- `LIBROSA_MCP_PORT`, default `8000`
- `LIBROSA_MCP_LOG_FILE`, default system temp file

## Releases

Releases are automated from commits on `main` or `master` using Python Semantic
Release. Use conventional commits:

- `fix: ...` creates a patch release.
- `feat: ...` creates a minor release.
- `feat!: ...` or `BREAKING CHANGE:` creates a major release.

The release workflow updates `pyproject.toml`, creates `CHANGELOG.md`, tags the
release as `vX.Y.Z`, builds the wheel/sdist, uploads them to the GitHub release,
and publishes to PyPI.

PyPI publishing uses a GitHub secret named `PYPI_API_TOKEN`. Create a PyPI API
token and add it to the repository or `pypi` environment secrets with that exact
name.

The workflow runs in the `pypi` GitHub environment, so environment protection
rules can be used if desired.
