@justmpm/flowmusic

MCP Server para FlowMusic -- criar, acompanhar e baixar musicas via API REST. Reaproveita a assinatura existente do usuario, sem necessidade da API oficial paga.

Tambem pode ser usado como CLI local para rodar os mesmos comandos fora do MCP, com help, saida em JSON, erros amigaveis e sugestoes de proximos passos.

Por que usar?

• 5 tools focadas -- Criacao de musicas, acompanhamento de status, download e autenticacao
• Login automatico via Chrome -- Abre o navegador, usuario faz login, tokens extraidos automaticamente via CDP. Zero config.
• Refresh automatico -- Renova token expirado sem intervencao
• Download em WAV/M4A -- Salva audio diretamente no disco
• CLI + MCP no mesmo pacote -- Use no terminal ou no cliente MCP, com a mesma logica por baixo
• Suite de testes com Vitest -- Validacao automatizada do MCP

Instalacao

npx (sem instalar, recomendado)

No seu config MCP (Claude Desktop, OpenCode, Cursor, etc.):

{
  "mcpServers": {
    "flowmusic": {
      "command": "npx",
      "args": ["-y", "@justmpm/flowmusic"]
    }
  }
}

Instalacao global

npm install -g @justmpm/flowmusic

{
  "mcpServers": {
    "flowmusic": {
      "command": "flowmusic-mcp"
    }
  }
}

CLI local

Depois de instalar globalmente, voce tambem pode usar:

flowmusic --help
flowmusic auth-status
flowmusic create-song --prompt "Lo-fi calmo para estudo" --title "Noite"

Autenticacao

O MCP suporta 4 formas de autenticacao. O login automatico via Chrome (CDP) e o metodo padrao -- basta chamar a tool login e o resto acontece sozinho.

1. Login automatico via Chrome (CDP) -- padrao, zero config

Basta chamar a tool login. O MCP:

1. Verifica se ja existe uma sessao valida em ~/.flowmusic/session.json
2. Se nao tiver, abre o Google Chrome com um perfil dedicado (~/.flowmusic/chrome-profile/)
3. Voce faz login normalmente no FlowMusic
4. Os tokens sao extraidos automaticamente via Chrome DevTools Protocol (CDP)
5. A sessao e salva em ~/.flowmusic/session.json para uso futuro

Na segunda vez, se o perfil do Chrome ainda estiver logado, a extracao e instantanea -- nenhum passo manual necessario.

// Exemplo de uso -- basta chamar a tool
{ "name": "login", "arguments": {} }

O parametro opcional mode controla o comportamento:

| Mode | Comportamento | |------|--------------| | auto (padrao) | Verifica sessao existente; se invalida, abre Chrome via CDP | | check | Apenas verifica se a sessao atual e valida (nao abre navegador) |

2. Token direto via variavel de ambiente

export FLOWMUSIC_ACCESS_TOKEN="seu-jwt-token-aqui"

Ideal para CI/CD ou ambientes sem navegador grafico.

3. Arquivo de sessao

Crie um arquivo JSON com tokens obtidos do Supabase:

{
  "access_token": "eyJ...",
  "refresh_token": "v1.st...",
  "expires_at": 1700000000
}

export FLOWMUSIC_SESSION_FILE="/caminho/para/sessao.json"

4. Cookie local (legado)

Extraia o cookie sb-sb-auth-token.0 do navegador (www.flowmusic.app) e salve em:

~/.flowmusic/cookies.json

O arquivo deve conter um array de cookies no formato:

[
  {
    "name": "sb-sb-auth-token.0",
    "value": "base64-encoded-json"
  }
]

Importante: O token JWT expira em ~1 hora. Se houver refresh_token disponivel, o MCP tenta renovar automaticamente. O login via CDP gerencia isso automaticamente.

Tools Disponiveis

| Tool | Descricao | Parametros obrigatorios | |------|-----------|------------------------| | login | Autentica e verifica sessao | Nenhum (opcional: mode) | | auth_status | Verifica status da autenticacao | Nenhum | | create_song | Cria nova musica | prompt | | get_song_status | Acompanha criacao de musica | operation_id (recebe o job_id retornado por create_song) | | download_audio | Baixa audio (WAV/M4A) | clip_id, output_path |

CLI

Ajuda geral

flowmusic --help

Ajuda de um comando especifico

flowmusic help create-song
flowmusic help get-song-status

Saida em JSON

flowmusic auth-status --json

Exemplos praticos

flowmusic login
flowmusic auth-status
flowmusic create-song --prompt "Lo-fi calmo com piano" --title "Noite"
flowmusic get-song-status --operation-id "<job_id>"
flowmusic download-audio --clip-id "<clip_id>" --output-path "D:/Music/noite.wav"

Caracteristicas da CLI

• aliases com - ou _ (create-song e create_song funcionam)
• help por comando
• --json para automacoes e scripts
• erros amigaveis com sugestoes do que fazer em seguida
• sugestoes de proximos passos apos comandos importantes como create-song

Configuracao

Com o login automatico via Chrome (CDP), nao e necessario configurar variaveis de ambiente -- basta chamar a tool login. Mas se preferir usar autenticacao manual, configure o token no seu cliente MCP:

Claude Desktop

{
  "mcpServers": {
    "flowmusic": {
      "command": "npx",
      "args": ["-y", "@justmpm/flowmusic"],
      "env": {
        "FLOWMUSIC_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

OpenCode

{
  "mcpServers": {
    "flowmusic": {
      "command": "npx",
      "args": ["-y", "@justmpm/flowmusic"],
      "env": {
        "FLOWMUSIC_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "flowmusic": {
      "command": "npx",
      "args": ["-y", "@justmpm/flowmusic"],
      "env": {
        "FLOWMUSIC_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Dica: Se usar o login CDP (padrao), nao precisa do campo env -- remova-o.

Exemplos de Uso

Criar musica e baixar

1. create_song(prompt="Uma batida eletronica com synth pads", title="Noite Digital")
2. get_song_status(operation_id="<job_id retornado acima>")
3. download_audio(clip_id="...", output_path="D:/Music/noite-digital.wav")

Login e verificacao

1. login(mode="auto")     -> autentica via Chrome CDP
2. auth_status()          -> confirma que a sessao esta ativa

Desenvolvimento

# Clonar repositorio
git clone https://github.com/justmpm/flowmusic-mcp.git
cd flowmusic-mcp

# Instalar dependencias
npm install

# Build
npm run build

# Build em modo watch
npm run dev

# Rodar testes
npm test

# Testes em modo watch
npm run test:watch

# Rodar localmente
npm start

Scripts

| Comando | Descricao | |---------|-----------| | npm run build | Compila TypeScript para dist/ | | npm run dev | Watch mode para desenvolvimento | | npm start | Inicia o servidor MCP | | npm test | Roda todos os testes | | npm run test:watch | Testes em modo watch |

Stack

| Tecnologia | Uso | |---|---| | TypeScript | Linguagem principal (strict mode) | | @modelcontextprotocol/sdk | MCP Server e transporte stdio | | Zod | Validacao de schemas de input | | chrome-launcher | Lanca Chrome com CDP e perfil dedicado | | ws | Cliente WebSocket para comunicacao CDP | | Vitest | Testes unitarios |

Estrutura do Projeto

flowmusic/
  src/
    index.ts          # Servidor MCP (Server + StdioServerTransport)
    cli.ts            # CLI local (flowmusic)
    types.ts          # Tipos: Clip, SongStatus, ToolResponse, etc.
    config.ts         # Constantes e logica de autenticacao
    utils.ts          # flowmusicFetch, ensureAuth, refreshAccessToken
    tool-registry.ts  # Registro centralizado das 5 tools
    package-version.ts # Leitura compartilhada da versao
    auth/
      index.ts        # Barrel export do modulo de autenticacao
      types.ts        # Tipos internos de auth (SessionData, AuthSource)
      flowmusic-auth.ts  # Logica principal de auth (token, refresh, validacao)
      chrome-launcher.ts # Lancamento do Chrome com perfil dedicado
      cdp-client.ts   # Cliente CDP (WebSocket + extracao de cookies)
    tools/
      index.ts        # Barrel export das 5 tools
      login.ts        # login
      auth-status.ts  # auth_status
      create-song.ts  # create_song
      get-song-status.ts # get_song_status
      download-audio.ts  # download_audio
  test/               # Testes unitarios
  dist/               # Build compilado
  package.json
  tsconfig.json
  vitest.config.ts
  README.md           # Este arquivo
  AGENTS.md           # Guia completo para subagents

Requisitos

• Node.js >= 18
• Google Chrome instalado (para login automatico via CDP)
• Conta ativa no FlowMusic

Licenca

MIT -- Koda AI Studio

Links

• Koda AI Studio: https://kodaai.app
• FlowMusic: https://www.flowmusic.app
• Model Context Protocol: https://modelcontextprotocol.io/
• Repositorio: https://github.com/justmpm/flowmusic-mcp