pitch-mcp

MCP server for real-time pitch detection and score alignment. Listens to a singer via microphone and reports their current position in a score and whether they are singing in tune.

What it does

Covers three goals:

  • Goal 4 — Show the current measure/beat position while singing
  • Goal 5 — Report pitch accuracy (too high / too low / on pitch)
  • Goal 6 — Identify where in the score a singer is based on a hummed or sung phrase

Supports both offline analysis of pre-recorded audio and real-time microphone input.

Tools

Tool Description
analyze_recording Offline: analyse a WAV file against a reference MusicXML score
load_score Load a MusicXML score into a named session; returns a session_id
start_monitoring Open the microphone and begin real-time pitch detection
get_current_position Poll the current score position and pitch accuracy
stop_monitoring Stop the microphone and return a session summary
list_capabilities Return server metadata: pitch backend, microphone availability

Installation

cd pitch-mcp
uv sync

For real-time monitoring (start_monitoring), PortAudio is required:

# Ubuntu / Debian
sudo apt install libportaudio2

Running

uv run pitch-mcp

Configuration

Variable Default Description
PITCH_BACKEND librosa Pitch detection algorithm: librosa or crepe

crepe requires a manual TensorFlow install (~500 MB) and downloads ~50 MB of model weights on first use. The default librosa backend (pYIN algorithm) works well for singing voice with no extra setup.

Usage examples

// Offline analysis of a recording
{
  "tool": "analyze_recording",
  "arguments": {
    "wav_path": "/path/to/recording.wav",
    "musicxml_path": "/path/to/score.mxl",
    "part_name": "Soprano"
  }
}

// Real-time session
{"tool": "load_score", "arguments": {"musicxml_path": "/path/to/score.mxl", "part_name": "Alto"}}
// → returns {"session_id": "abc123"}

{"tool": "start_monitoring", "arguments": {"session_id": "abc123"}}
{"tool": "get_current_position", "arguments": {"session_id": "abc123"}}
// → returns measure, beat, expected pitch, detected pitch, accuracy

{"tool": "stop_monitoring", "arguments": {"session_id": "abc123"}}

Audio must be 16-bit PCM WAV. MP3 and FLAC are not supported.

Testing

# Unit tests (no microphone or audio required)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v

# Integration tests (uses pre-recorded WAV files)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m integration

# Manual tests (requires a real microphone — skip in CI)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v -m manual

Dependencies

  • librosa — pYIN pitch detection (primary backend, pure Python)
  • music21 — score parsing and pitch calculations
  • sounddevice — real-time microphone input
  • numpy, scipy — numerics
  • mcp — MCP protocol

System requirements

  • Python 3.12+
  • libportaudio2 — required for real-time microphone input (start_monitoring)
  • No system libraries required for offline analysis

Phase status

Phase Status
Phase A — offline analysis Complete (93/93 tests pass)
Phase B — real-time monitoring Session framework in place; microphone integration ready

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for raulkivi from gravatar.com raulkivi

Credits

Author: Music Assistant Contributors

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.12

Provides Extra

dev

Tags

audio choir mcp music musicxml pitch

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pitch_mcp-0.1.3.tar.gz (145.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pitch_mcp-0.1.3-py3-none-any.whl (17.6 kB view details)

Uploaded Python 3

File details

Details for the file pitch_mcp-0.1.3.tar.gz.

File metadata

  • Download URL: pitch_mcp-0.1.3.tar.gz
  • Upload date:
  • Size: 145.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pitch_mcp-0.1.3.tar.gz
Algorithm Hash digest
SHA256 1ee7503f3e5c6d73bc13a698d4e63d325f6143e55a23626c7187cf6dfb0e366b
MD5 b90d46063dfc0f2924b42711fb81fd0f
BLAKE2b-256 e9b0cd257df526fe2c0654a21cb28df8040fc19633ac67a502106a31a5ccbafb

See more details on using hashes here.

Provenance

The following attestation bundles were made for pitch_mcp-0.1.3.tar.gz:

Publisher: publish.yml on raulkivi/music-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pitch_mcp-0.1.3-py3-none-any.whl.

File metadata

  • Download URL: pitch_mcp-0.1.3-py3-none-any.whl
  • Upload date:
  • Size: 17.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pitch_mcp-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b0e7beeff5c19cf9453594b7e0326ac7d9cf334013cbb007e412bb963095a52f
MD5 cc5607b695855517fc3fb23a3e88b3d0
BLAKE2b-256 83d331ba982fdf0c7e3bcf48eb3bce9ef07e7fca116935e141c0e0b9516a5b8b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pitch_mcp-0.1.3-py3-none-any.whl:

Publisher: publish.yml on raulkivi/music-assistant

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.0

2 files

This release

0.1.3 This release

2 files

0.1.2

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page