Skip to main content
Glama
Mingus Chord Suggestion Tool

Mingus Chord Suggestion Tool

by sarunabh

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers