mcp-local-music-analysis 0.1.0

Local MCP server for music and audio analysis with librosa.

MCP Local Music Analysis

Local Model Context Protocol server for music and audio analysis with librosa. It exposes one comprehensive analysis tool for local audio files.

Setup

Add this server to your MCP client configuration:

{
  "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:

uvx -n mcp_local_music_analysis --transport http

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

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:

{
  "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.

Run a full analysis of this audio file.

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

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

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

Local development

For local development from a checkout of this repository:

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:

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

For a direct Python run:

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.