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

Installation

cd pitch-mcp
uv sync

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

# Ubuntu / Debian
sudo apt install libportaudio2

Quick install: on Ubuntu/Debian/Linux Mint, bash install.sh handles uv and the optional libportaudio2 install for you — see SETUP.md for the full non-technical walkthrough. Ready-made client configs (Claude Desktop, Cursor, Windsurf, Continue, Zed) are in examples/. If something goes wrong, check TROUBLESHOOTING.md.

Running

uv run pitch-mcp

Configuration

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

All 100 current tests are unit tests, run against mocks and synthetic (in-memory) WAV data — none require real audio hardware or pre-recorded fixtures.

The integration and manual pytest markers are registered in pyproject.toml and reserved for future Phase B work (fixture-based offline analysis and real-microphone tests, respectively), but no tests are marked with them yet, so -m integration / -m manual currently select nothing.

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