flat-mcp — edite suas partituras do Flat.io pelo Claude

Criado por @eubrunodiego · 2026-10-27

Servidor MCP local que conecta o Claude (app desktop) diretamente à REST API do Flat.io usando a sua conta, por meio de um token pessoal. Com ele, o Claude consegue listar, ler, editar, restaurar, exportar e criar partituras.

Por que não usar o conector oficial do Flat?

O Flat oferece um servidor MCP oficial (https://mcp.flat.io/mcp), mas ele só lê e cria partituras — não edita as existentes — e exige assinatura Flat Power. Esta integração fala direto com a REST API, onde editar é possível.

Related MCP server: google-drive-mcp

Como a edição funciona

A API do Flat não altera notas "no lugar": cada edição grava uma nova revisão da partitura (POST /scores/{id}/revisions). O fluxo de cada ferramenta de edição é:

1. baixa a última revisão em MusicXML;

2. aplica a alteração (troca de compassos ou substituição exata de texto);

3. valida o XML — se ficar inválido, nada é gravado;

4. grava a nova revisão com uma descrição do que mudou.

Nada é apagado. Para desfazer, peça ao Claude para restaurar uma revisão anterior.

Atenção: a documentação do Flat avisa que a última revisão pode não refletir alterações muito recentes feitas no editor web (ele consolida revisões a cada ~100 modificações). Antes de editar pela API, feche a partitura no navegador ou salve uma revisão manualmente, para não sobrescrever trabalho recente.

1. Gere seu token pessoal

1. Acesse https://flat.io/developers/apps e crie um app (ex.: "Claude").

2. No menu lateral, abra REST API → Personal tokens.

3. Dê um nome ao token e marque os escopos: scores, collections e account.public_profile.

4. Copie o token e guarde-o — ele dá acesso total às suas partituras.

2. Instale

2.1 Instale o uv

O uv instala o Python e as dependências sozinho.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Anote o caminho completo do executável, que será usado no passo 3:

which uv          # macOS/Linux — ex.: /Users/voce/.local/bin/uv

where.exe uv      # Windows — ex.: C:\Users\voce\.local\bin\uv.exe

2.2 Baixe este repositório

Coloque-o num local fixo (não mova a pasta depois de configurar):

git clone https://github.com/eubrunodiego/flat-mcp.git ~/flat-mcp

Sem git, use Code → Download ZIP no GitHub e descompacte em ~/flat-mcp.

2.3 Teste a conexão

cd ~/flat-mcp
FLAT_ACCESS_TOKEN=cole-seu-token-aqui uv run python -c "from flat_mcp import FlatClient; print(FlatClient().me()['username'])"

Se aparecer seu nome de usuário do Flat, está tudo certo.

cd ~/flat-mcp
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install .

No passo 3, use como command o caminho completo de .venv/bin/flat-mcp (Windows: .venv\Scripts\flat-mcp.exe) e deixe args vazio.

3. Conecte ao Claude

3.1 Claude desktop (macOS e Windows)

1. No app Claude, abra Configurações → Desenvolvedor → Editar configuração. Isso abre o arquivo claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Acrescente a chave mcpServers no nível de cima do arquivo, ao lado das chaves que já existem (não dentro de preferences). Lembre da vírgula depois do bloco anterior:

{
  "preferences": { "...": "o que já existia no seu arquivo" },
  "mcpServers": {
    "flat": {
      "command": "/CAMINHO/COMPLETO/DO/uv",
      "args": ["--directory", "/CAMINHO/COMPLETO/flat-mcp", "run", "flat-mcp"],
      "env": {
        "FLAT_ACCESS_TOKEN": "cole-seu-token-aqui",
        "FLAT_EXPORT_DIR": "/CAMINHO/onde/salvar/exportacoes"
      }
    }
  }
}

• command: o caminho completo do uv anotado no passo 2.1. Use o caminho completo — o app nem sempre enxerga o PATH do terminal.

• --directory: o caminho completo da pasta deste repositório.

• No Windows, escreva as barras dobradas: "C:\\Users\\voce\\flat-mcp".

• FLAT_EXPORT_DIR é opcional (padrão: pasta Downloads).

3. Confira se o JSON é válido:

python3 -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json" > /dev/null && echo "JSON OK"

4. Feche o Claude por completo (⌘Q no macOS; no Windows, saia pelo ícone da bandeja) e abra de novo. As ferramentas flat_* aparecem no menu de ferramentas da conversa. Peça "teste a conexão com o Flat" para confirmar.

3.2 Claude Code (terminal)

claude mcp add flat --scope user \
  --env FLAT_ACCESS_TOKEN=cole-seu-token-aqui \
  -- uv --directory ~/flat-mcp run flat-mcp

Confira com claude mcp list. Dentro do Claude Code, /mcp mostra o status.

3.3 Resolução de problemas

Os registros do servidor ficam em:

• macOS: ~/Library/Logs/Claude/mcp-server-flat.log

• Windows: %APPDATA%\Claude\logs\mcp-server-flat.log

4. Use

Exemplos de pedidos:

• "Liste minhas partituras do Flat modificadas recentemente."

• "Na partitura Ave Maria, mostre os compassos 9 a 16 do Contralto."

• "No compasso 12 do Soprano, troque o Fá por Sol e mantenha o ritmo. Mostre o dry-run antes de gravar."

• "Corrija o título para 'Ave Maria (Schubert)' e o compositor para 'F. Schubert'."

• "Desfaça a última edição da partitura X."

• "Exporte a partitura X em PDF e em MusicXML."

Ferramentas

flat_replace_measures e flat_edit_musicxml aceitam dry_run=true, que confere o resultado sem gravar.

Usar como biblioteca Python

from flat_mcp import FlatClient
from flat_mcp import musicxml as mx

flat = FlatClient()  # lê FLAT_ACCESS_TOKEN
scores, _ = flat.list_scores()
sid = scores[0]["id"]

xml = flat.get_musicxml(sid)
print(mx.summarize(xml))
novo = mx.apply_text_edits(xml, [{"find": "<work-title>Rascunho</work-title>",
                                   "replace": "<work-title>Versão final</work-title>"}])
flat.create_revision(sid, novo, description="Título final")

Segurança

• O token fica apenas no seu computador (variável de ambiente). Não o coloque em repositórios. Para revogá-lo, apague-o em https://flat.io/developers/apps.

• Partituras criadas são privadas por padrão; tornar pública exige que você peça.

• Os escopos scores/collections permitem apagar partituras pela API, mas este servidor não expõe nenhuma ferramenta de exclusão.

Testes

uv run --extra dev pytest -q

Os testes usam uma API do Flat simulada em memória — não tocam na sua conta.

Limitações

• Edição por compasso suporta MusicXML score-partwise (o formato que o Flat exporta).

• Exportações pesadas (MP3/WAV/PDF de partituras longas) podem demorar; o tempo limite é 60 s.

• Limites de requisição da API: veja https://flat.io/developers/docs/api/rate-limits.

Créditos e licença

Desenvolvido por @eubrunodiego em 2026-10-27.

Distribuído sob a licença MIT. Você pode usar, modificar e redistribuir, desde que mantenha o aviso de copyright.

Este projeto não é afiliado ao Flat.io (Tutteo Ltd). "Flat" é marca de seus respectivos donos.