Mingus Chord Suggestion Tool

An MCP server that takes a chord progression, identifies what's not working, applies a style filter, and returns chord suggestions backed by music theory and Claude's reasoning.

Architecture

┌─────────────────────────────────────────────────┐
│                   MCP Client                    │
│              (Claude Desktop, etc.)             │
└────────────────────┬────────────────────────────┘
                     │ stdio (JSON-RPC)
┌────────────────────▼────────────────────────────┐
│                  server.py                      │
│           MCP tool: suggest_chords              │
└──────┬───────────────────────┬──────────────────┘
       │                       │
┌──────▼──────┐       ┌────────▼────────┐
│music_theory │       │    style.py     │
│    .py      │       │                 │
│             │       │ vibe vocabulary │
│ - parse     │       │ - annotate      │
│   chords    │       │   candidates    │
│ - infer key │       │ - extended      │
│ - generate  │       │   chord gens    │
│   diatonic  │       │   (jazz/rnb)    │
│   + borrowed│       └────────┬────────┘
│   candidates│                │
└──────┬──────┘                │
       │    top candidates     │
       └───────────┬───────────┘
                   │
         ┌─────────▼──────────┐
         │  claude_advisor.py │
         │                    │
         │  Anthropic API     │
         │  - final selection │
         │  - theory rationale│
         │  - vibe rationale  │
         │  - placement hint  │
         └────────────────────┘

Three-layer design

Layer 1 — music_theory.py (mingus)

• Parses chord shorthand to note sets

• Infers the most likely key by scoring all major/minor keys against the note content of the input chords

• Generates diatonic triads, diatonic seventh chords, and common borrowed chords (bVII, bVI, minor iv) as raw candidates

Layer 2 — style.py (rule-based filter)

• Maps each vibe to a chord vocabulary: preferred chord types, preferred quality suffixes

• Scores and labels each candidate as strong fit, possible, or unlikely

• Generates vibe-specific extended chords (jazz: maj9/m9/dom9/m7b5; R&B: sus4/7sus4/m9)

Layer 3 — claude_advisor.py (Anthropic API)

• Receives the top-scored candidates, the inferred key, the issue, and the vibe description

• Selects 2-3 final suggestions, writing theory rationale and vibe rationale for each

• Can go outside the candidate list if a better option exists

• Returns structured JSON

Related MCP server: vibe-prompt-mcp

Tool interface

Tool name: suggest_chords

Input:

{
  "chords": ["Em", "Gmaj7"],
  "issue": "want a third chord that creates tension before resolving back to Em",
  "vibe": "jazzy"
}

Output:

{
  "suggestions": [
    {
      "chord": "Am7",
      "theory": "Am7 is the vi7 in G major, a minor subdominant with a 7th. It creates a ii-V-I feel when followed by D7 → Gmaj7, or delivers a deceptive resolution if you return to Em instead.",
      "vibe_rationale": "The m7 quality is a jazz staple. The A-C-E-G voicing offers smooth voice leading from Gmaj7 (G-B-D-F#) by dropping B to A and F# to G.",
      "placement": "Between Gmaj7 and Em as a passing chord"
    }
  ],
  "overall_note": "The progression has a vi-I feel; adding a ii chord turns it into a classic jazz ii-I-vi loop.",
  "context": {
    "inferred_key": "G major",
    "input_progression": ["Em", "Gmaj7"],
    "vibe": "jazzy",
    "candidate_count": 21
  }
}

Setup

1. Install dependencies

cd mingus-chord-tool
pip install -r requirements.txt

2. Set the API key

export ANTHROPIC_API_KEY="sk-ant-..."

3. Register with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mingus-chord-tool": {
      "command": "python",
      "args": ["/absolute/path/to/mingus-chord-tool/server.py"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Restart Claude Desktop. The suggest_chords tool will appear in the tools panel.

4. Test without Claude Desktop

python -c "
from music_theory import summarize_theory
from style import annotate_candidates, get_vibe_context

theory = summarize_theory(['Em', 'Gmaj7'])
print('Key:', theory['inferred_key'], theory['inferred_mode'])
scored = annotate_candidates(theory['novel_candidates'], 'jazzy')
for c in scored[:5]:
    print(c['chord'], '-', c['vibe_label'])
"

Design decisions

Why not Spotify? Spotify's API exposes audio features (tempo, energy, valence) but not chord data. Chord inference from audio exists but is error-prone and adds a heavy dependency. Mingus computes harmony directly, which is more reliable for this use case.

Why mingus for theory and Claude for suggestions? Mingus is deterministic -- it generates every diatonic and borrowed candidate without hallucinating. Claude's strength is contextual judgment: picking between candidates, balancing tension vs. resolution, and writing coherent rationale. Splitting the work this way means Claude never invents notes that don't belong to a chord, while still applying musical taste.

Why a scored candidate list rather than asking Claude to reason from scratch? Passing scored candidates constrains the search space and gives Claude grounding. It also means the vibe_label in the output is independently computed -- you can verify it against the theory layer without trusting Claude's self-report.

Key inference method The server scores every major and minor key by counting how many notes in the input chords belong to that key. This is a weighted note-overlap approach, not a full Roman numeral analysis. It works well for common progressions but will misfire on heavily chromatic or modal music. A more robust approach would add Roman numeral parsing and handle secondary dominants explicitly.

Extending

• Add modal as a vibe (Dorian: ii7, bVII; Lydian: #IV, I; Phrygian: bII)

• Add a mode override parameter to skip key inference

• Add a secondary_dominants layer that computes V/ii, V/IV, V/V for each candidate

• Persist suggestion history and detect patterns across sessions