@playbykey/mcp

@playbykey/theory-mcp exposes @playbykey/theory as an MCP stdio server. MCP lets an AI assistant call the theory engine directly as tools instead of reasoning about scales, modes, and key relationships from training data. Music theory relationships, resolved deterministically through fixed interval and scale-degree relationships. No global install needed - npx fetches and runs the package on demand.

Requires Node.js (for npx).

Setup

Claude Desktop

Edit the MCP config file (claude_desktop_config.json) via Claude Desktop’s settings.

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Restart Claude Desktop after saving, then check its settings to confirm theory shows as connected.

Cursor

Config file location:

• Global (all projects): ~/.cursor/mcp.json
• Project only: .cursor/mcp.json in your project root

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Restart Cursor after saving, then check its MCP settings to confirm theory shows as connected.

Claude Code

Project scope (recommended) - commit an .mcp.json at your repo root so the server is available to every contributor after git clone:

{
  "mcpServers": {
    "theory": {
      "command": "npx",
      "args": ["-y", "@playbykey/theory-mcp"]
    }
  }
}

Local scope - register the server for yourself in this project only, without committing anything:

claude mcp add theory npx -y @playbykey/theory-mcp

Global scope - register the server for yourself across every project on this machine:

claude mcp add theory npx -y @playbykey/theory-mcp --scope user

Run claude mcp list to confirm theory shows as connected.

Tools

Modes

Tool	Input	Returns
get_mode_notes	root, mode	The 7 notes of a diatonic mode
get_parent_scale_modes	root, mode	All 7 modal rotations of the parent key
get_modal_root	parent_key, mode	The root note of a mode within a parent major key
get_relative_minor	major_key	The relative minor root for a major key
get_relative_major	minor_key	The relative major root for a minor key
get_mode_info	mode	Display metadata: name, scale degree, character

Circle of fifths

Tool	Input	Returns
get_circle_of_fifths	none	All 12 chromatic notes in ascending-fifths order from C

Key signatures

Tool	Input	Returns
get_key_signature	key	Sharp or flat count for a key, treated as a major-key tonic (minor-key signatures are not exposed by this tool)

Scales

Tool	Input	Returns
get_scale_notes	root, scale_type	Notes of a scale (major, blues, pentatonic-major, pentatonic-minor, harmonic-minor, melodic-minor, chromatic)
build_note_map	root, scale_type	Per-note data: note name, scale degree, semitone offset from root
get_scale_degree	root, scale_type, note	1-based scale degree of a note, or null if not in scale
is_note_in_scale	root, scale_type, note	Whether a note belongs to a scale
get_melodic_minor_notes	root	The 7 notes of the ascending melodic minor scale
get_melodic_minor_mode_notes	root, mode	The 7 notes of a melodic minor mode
get_harmonic_minor_mode_notes	root, mode	The 7 notes of a harmonic minor mode
get_bebop_scale_notes	root, type	The 8 notes of a bebop scale variant

Intervals

Tool	Input	Returns
resolve_interval	root, interval	From-note and to-note for a named interval within a root context
get_semitone_distance	from, to	Ascending semitone distance between two notes (0-11)

Note spelling

Tool	Input	Returns
get_sharps	notes (sharp or flat)	Notes normalized to canonical sharp spelling
get_flats	notes (must be sharp-spelled)	Notes respelled as flats
get_enharmonic_labels	notes (must be sharp-spelled)	Combined sharp/flat display labels (e.g. "Db/C#")

Chords

Tool	Input	Returns
get_chord_notes	root, chord_type	Notes of a chord type built on a root
get_diatonic_chords	root, mode (optional, defaults to ionian)	The 7 diatonic triads for a key/mode, one per scale degree
get_chord_by_degree	degree, root, mode (optional, defaults to ionian)	The diatonic chord at a specific scale degree (1-7)
get_available_inversions	chord_type	Valid inversion numbers for a chord type
get_chord_inversion	root, chord_type, inversion	Chord notes reordered so the given inversion’s tone is lowest

Progressions

Tool	Input	Returns
get_progression_in_key	progression_id, root	A named catalog progression rendered as chords in a given key
get_roman_numeral	degree, mode (optional, defaults to ionian)	Roman numeral for a scale degree in a mode

Transposition

Tool	Input	Returns
transpose	notes, from_root, to_root	Notes shifted from one key to another by the semitone distance between the roots

MIDI & Frequency

Tool	Input	Returns
note_to_midi	note, octave	MIDI note number, using scientific pitch notation (C4 = middle C = MIDI 60)
midi_to_note	midi_number	Note and octave for a MIDI number - the inverse of note_to_midi
note_to_frequency	note, octave	Frequency in Hz, equal temperament (A4 = 440Hz)