music21-mcp

music21 MCP Server

Servidor MCP de análise musical usando music21 + FastMCP + Pydantic.

Complementa o seu MIDI-compostion-tools-MCP focado em construção: enquanto o toolkit constrói composições, este servidor analisa arquivos existentes.

---

🛠 Tools disponíveis (8)

| Tool | O que faz | |---|---| | score_info | Visão geral: título, compositor, partes, assinaturas, duração | | analyze_key | Detecta tonalidade (algoritmo Krumhansl-Schmuckler) com confiança | | analyze_harmony | Extrai acordes, numerais romanos, cadências, progressão resumida | | analyze_melody | Contorno, âmbito, intervalos, clímax, lista de notas | | analyze_rhythm | Fórmula de compasso, tempo, densidade, síncope, padrões rítmicos | | analyze_form | Detecta seções (A, B, A'…), repetições, forma geral (ABA, Rondó…) | | check_counterpoint | Erros de voice-leading: quintas paralelas, cruzamentos, saltos | | analyze_motifs | Motivos recorrentes e suas transformações (inversão, retrogrado…) |

---

📦 Instalação

# 1. Clonar / copiar a pasta music21-mcp
cd music21-mcp

# 2. Criar ambiente virtual (recomendado)
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows

# 3. Instalar dependências
pip install -r requirements.txt

---

▶️ Executar

python server.py

O servidor roda via stdio — padrão para integração local com Claude Desktop, Cursor, etc.

---

⚙️ Configuração no Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "music21": {
      "command": "python",
      "args": ["/caminho/absoluto/para/music21-mcp/server.py"],
      "env": {}
    }
  }
}

Dica: se usar virtualenv, use o Python do venv: "/caminho/para/music21-mcp/.venv/bin/python"

---

🔗 Integração com seu MCP Music Toolkit

Pipeline típico:

music21 MCP (analyze_harmony)
    → detecta progressão do arquivo
    → passa para seu toolkit (comp_set_progression)
    → gera variação ou arranjo

music21 MCP (check_counterpoint)
    → aponta erros no MIDI gerado
    → seu toolkit (theory_voice_lead_sequence)
    → corrige o voice leading

---

📁 Estrutura

music21-mcp/
├── server.py              # FastMCP — 8 tools registradas
├── models.py              # Pydantic schemas input/output
├── requirements.txt
├── analyzers/
│   ├── harmony.py         # Acordes + numerais romanos + cadências
│   ├── melody.py          # Contorno, âmbito, intervalos
│   ├── rhythm.py          # Tempo, densidade, síncope
│   ├── form.py            # Seções e forma musical
│   ├── counterpoint.py    # Erros de contraponto/voice-leading
│   ├── score_info.py      # Metadados e visão geral
│   └── motifs.py          # Padrões motívicos recorrentes
└── utils/
    └── loader.py          # Carregar arquivos + helpers music21

---

💡 Exemplo de uso

# analyze_key
{
  "file_path": "/home/user/bach_prelude.mid",
  "response_format": "json"
}

# analyze_harmony com recorte de compasses
{
  "file_path": "/home/user/sonata.xml",
  "measures": [1, 16],
  "response_format": "markdown"
}

# analyze_motifs customizado
{
  "file_path": "/home/user/symphony.mid",
  "motif_length": 5,
  "min_occurrences": 3
}