@justmpm/flowmusic

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

Por que usar?

• 13 tools completas -- Criacao de musicas, download, videos musicais, billing
• 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
• Videos musicais -- Gera videos a partir de musicas existentes
• 184 testes -- Suite abrangente com Vitest

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"
    }
  }
}

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:

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

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. list_clips()
3. get_clip(clip_id="...")
4. download_audio(clip_id="...", output_path="D:/Music/noite-digital.wav")

Criar video musical

1. list_clips()
2. create_music_video(clip_id="...", prompt="Visualizer abstrato com particulas", aspect_ratio="16:9")
3. get_music_video_status(job_id="...")

Verificar creditos

1. get_credits()
2. get_subscription()

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 (184 testes)
npm test

# Testes em modo watch
npm run test:watch

# Rodar localmente
npm start

Scripts

Stack

Estrutura do Projeto

flowmusic/
  src/
    index.ts          # Servidor MCP (Server + StdioServerTransport)
    types.ts          # Tipos: Clip, SongStatus, ToolResponse, etc.
    config.ts         # Constantes e logica de autenticacao
    utils.ts          # flowmusicFetch, ensureAuth, refreshAccessToken
    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 13 tools
      login.ts        # login
      auth-status.ts  # auth_status
      list-clips.ts   # list_clips
      get-clip.ts     # get_clip
      create-song.ts  # create_song
      get-song-status.ts # get_song_status
      download-audio.ts  # download_audio
      list-conversations.ts # list_conversations
      create-conversation.ts # create_conversation
      get-credits.ts  # get_credits
      get-subscription.ts # get_subscription
      create-music-video.ts # create_music_video
      get-music-video-status.ts # get_music_video_status
  test/               # 184 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