Serato DJ MCP (serato-dj-mcp)

serato-dj-mcp

Pergunte ao Claude sobre sua biblioteca do Serato DJ: encontre faixas que se misturam harmonicamente por BPM e chave Camelot, navegue por suas crates, audite a biblioteca em busca de duplicatas e arquivos ausentes, e tenha novas crates criadas para você, exibidas antes que qualquer coisa seja gravada. Funciona através do Model Context Protocol (MCP), a forma padrão de aplicativos de IA como Claude Desktop, Claude Code, Cursor e VS Code se conectarem a ferramentas no seu computador: este é um pequeno servidor local que responde a partir da sua biblioteca e não envia nada para lugar nenhum.

Status: experimental. Pré-1.0 e em desenvolvimento ativo: uma versão menor pode alterar comportamento ou quebrar compatibilidade, um patch nunca o faz.

[!IMPORTANT] Não afiliado, endossado ou suportado pela Serato. Serato e Serato DJ são marcas registradas de seus respectivos proprietários. Este projeto lê um layout de banco de dados de engenharia reversa e pode parar de funcionar após qualquer atualização da Serato.

O que você pode perguntar

Uma vez que o servidor esteja conectado, você fala com seu assistente normalmente:

• "Encontre faixas entre 122 e 126 BPM em 8A ou 9A que eu adicionei este ano."
• "Me dê faixas que se misturam harmonicamente a partir de 8A, por volta de 124 BPM."
• "Mostre-me o que está na minha crate Warm Up, em ordem."
• "Audite minha biblioteca: duplicatas, arquivos ausentes, faixas que não estão em nenhuma crate."
• "Quais faixas na minha biblioteca não têm BPM ou não têm chave?"

Com a escrita de crates ativada:

• "Crie uma crate chamada Friday Opening com as vinte faixas que você acabou de encontrar, e me mostre a lista antes de escrever qualquer coisa." Depois, quando você fechar o Serato: "Aplique a crate preparada."

O assistente faz a busca; o servidor responde a partir da sua biblioteca e, quando solicitado, escreve apenas o que você aprovou.

Instalação

Funciona no macOS. Testado com Serato DJ Lite 4.0.9 no macOS; a suíte de testes roda em CI no macOS e Linux com Node.js 22.16 e 24. Windows não foi testado — veja Compatibilidade. A extensão do Claude Desktop e a configuração do Claude Code abaixo foram testadas manualmente no macOS; as configurações do Cursor e do VS Code seguem a documentação desses editores e não foram testadas.

Cada configuração inicia o servidor somente leitura. A escrita de crates é um recurso separado, descrito abaixo.

Claude Desktop

Como uma extensão (sem necessidade de Node.js). Baixe serato-dj-mcp-<version>.mcpb do último lançamento (anexado a partir da versão 0.1.1) e abra-o; o Claude Desktop mostra o que ele contém e o instala. Suas configurações permitem apontá-lo para uma pasta de biblioteca e ativar a escrita de crates ou SQL bruto; todas as três podem permanecer como estão.

Ou manualmente, com Node.js 22.16 ou mais recente instalado: abra Configurações → Desenvolvedor → Editar Config e adicione o servidor a claude_desktop_config.json, depois reinicie o Claude Desktop.

{
  "mcpServers": {
    "serato": {
      "command": "npx",
      "args": ["-y", "serato-dj-mcp"]
    }
  }
}

Claude Code

claude mcp add serato -- npx -y serato-dj-mcp

Adicione --scope user antes de serato para tê-lo em todos os projetos. O repositório também é um plugin do Claude Code que inicia o mesmo comando.

Cursor

Adicionar ao Cursor, ou adicione a mesma entrada mcpServers como para o Claude Desktop em ~/.cursor/mcp.json. O link abre cursor://anysphere.cursor-deeplink/mcp/install?name=serato&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcmF0by1kai1tY3AiXX0=, que pede ao Cursor para adicionar {"command":"npx","args":["-y","serato-dj-mcp"]} sob o nome serato.

VS Code

Instalar no VS Code, ou a partir de um terminal:

code --add-mcp '{"name":"serato","type":"stdio","command":"npx","args":["-y","serato-dj-mcp"]}'

Opções para qualquer cliente

Adicione opções após serato-dj-mcp em args, por exemplo "args": ["-y", "serato-dj-mcp", "--allow-writes"]:

• --library <path> — a pasta da biblioteca Serato (a que contém master.sqlite). Não é necessária no macOS, onde a biblioteca em ~/Library/Application Support/Serato e em unidades montadas é encontrada automaticamente.
• --allow-writes — escrita de crates, veja abaixo.
• --allow-raw-sql — adiciona run_sql, SQL somente leitura para desenvolvedores.

Todas as opções estão listadas em Opções.

node:sqlite é uma API Node experimental e imprime um aviso no stderr; isso é esperado e inofensivo, porque o protocolo MCP trafega pelo stdout.

A partir do código-fonte, para desenvolvedores

git clone https://github.com/Venut-Technologies/serato-dj-mcp.git
cd serato-dj-mcp
npm ci
npm run build

Depois use "command": "node" com "args": ["/absolute/path/to/serato-dj-mcp/dist/index.js"], ou claude mcp add serato -- node /absolute/path/to/serato-dj-mcp/dist/index.js.

O que o servidor lê, escreve e envia está em PRIVACY.md: ele não faz requisições de rede e não tem telemetria.

Compatibilidade

Serato DJ 4.x	Suportado. Desenvolvido e testado contra Serato DJ Lite 4.0.9 (esquema de biblioteca 202). Outras versões de esquema 4.x são lidas com um aviso schema_unknown. Espera-se que o Serato DJ Pro 4.x use o mesmo formato de biblioteca, mas não foi testado.
Serato DJ 3.x	Detectado e relatado, não lido (mantém um database V2 binário em vez de SQLite).
macOS	Suportado. É onde o projeto é desenvolvido, e o CI roda nele.
Windows	Não testado. O servidor não tem tratamento específico para Windows: passe --library explicitamente, porque a descoberta automática só conhece o layout do macOS, e espere diretórios de cache e estado no estilo macOS sob sua pasta de usuário. A verificação "o Serato está rodando" usa ps, que o Windows não tem, então apply_changes pode se recusar a escrever em vez de adivinhar.
Linux	O Serato não roda no Linux; a suíte de testes roda lá em CI com fixtures sintéticas.
Node.js	22.16 ou mais recente, porque backup() de node:sqlite chega lá. Não é presumido: o CI roda toda a suíte em 22.16 e em 24, no macOS e no Ubuntu.
Extensão do Claude Desktop	Roda no próprio Node.js do Claude Desktop, não no seu. Verificado manualmente em 2026-09-24 com Claude Desktop 2.7032.0 no macOS, cujo Node.js embutido é 24.21: instalado, então list_libraries e list_crates responderam com os dados da biblioteca.

Tudo o que este servidor assume sobre a biblioteca Serato está documentado em docs/serato-4x-notes.md, com a medição por trás de cada afirmação.

Somente leitura por padrão, escrita sob solicitação

Por padrão, o servidor nunca escreve nos arquivos do Serato. Cada leitura passa por uma cópia instantânea do banco de dados da biblioteca em --cache-dir, então uma pergunta do assistente não pode alterar sua biblioteca, esteja o Serato aberto ou não.

Duas flags ampliam isso, e cada uma registra ferramentas extras apenas quando é fornecida — uma ferramenta que não existe não pode ser chamada por engano:

• --allow-raw-sql adiciona run_sql: SELECT somente leitura contra o instantâneo, retornando linhas brutas.
• --allow-writes adiciona stage_crate, preview_changes, apply_changes e discard_changes. A escrita é dividida em duas: as crates são preparadas primeiro, o que nunca toca na biblioteca, e são aplicadas apenas quando você confirma e o Serato está fechado. Ambos os bancos de dados são copiados antes de cada escrita. Os detalhes estão em Escrevendo na biblioteca.

Ferramentas

• list_libraries — as bibliotecas que este servidor pode ver, com versão, versão de esquema e locais. Os caminhos aqui não são mascarados, então você pode copiar um para --library.
• search_tracks — busca por texto livre, BPM, chave, gênero, avaliação, data de adição, associação a crates e flags. A tonalidade é Camelot; uma faixa cuja chave o próprio Serato não conseguiu analisar ainda é correspondida, e key_source diz de onde a chave veio. Paginado com um cursor opaco; a página padrão é de 25 faixas e nove campos.
• get_tracks — busca faixas pelos ids search_tracks retornados. Ids desconhecidos vêm de volta em missing em vez de serem descartados.
• list_crates — as crates no espaço da Biblioteca Serato, com seu caminho de exibição e quantas faixas distintas cada uma contém. Crates inteligentes, raízes de espaço e outros espaços internos do Serato (como o painel Prepare) não são listados.
• get_crate_tracks — as faixas de uma crate, na ordem da própria crate. Apenas crates no espaço da Biblioteca Serato podem ser fornecidas.
• audit_library — diagnostica a biblioteca. Cada verificação roda por padrão e relata uma contagem mais até dez ids de faixas de exemplo: faixas sem BPM, sem chave alguma, com uma chave que o próprio Serato não consegue exibir, marcadas como obsoletas, em nenhuma crate, somente streaming, duplicadas, e com caminhos quebrados. duplicates relata grupos em vez de ids soltos, porque qual faixa duplica qual é a parte em que você pode agir. broken_paths lê a flag de ausência do próprio Serato por padrão; passe check_filesystem: true para também verificar no disco, o que é opcional porque um stat contra uma unidade desconectada bloqueia por segundos. Uma unidade que não está montada é relatada como tal em vez de ter todas as suas faixas declaradas ausentes.
• run_sql — um SELECT somente leitura contra uma cópia instantânea. Registrado apenas com --allow-raw-sql, porque retorna linhas brutas sem mascaramento de caminho.

Com --allow-writes:

• stage_crate — prepara uma nova crate a partir de ids de faixas. Nada é escrito ainda; a resposta lista cada faixa preparada por título e artista, então verifique.
• preview_changes — mostra o que está preparado, com format: "detail" até cada faixa.
• apply_changes — escreve tudo o que está preparado, tudo ou nada. Recusado enquanto o Serato está rodando.
• discard_changes — descarta uma crate preparada, ou todas elas.

Opções

--library <path>, --root <dir> (repetível), --cache-dir <dir>, --state-dir <dir>, --allow-raw-sql, --allow-writes, --help, --version. SERATO_LIBRARY_PATH é uma alternativa a --library; a flag vence. Uma opção desconhecida é um erro, não um no-op.

Escrevendo na biblioteca

Escritas precisam de --allow-writes e acontecem em duas etapas, porque o Serato deve estar fechado enquanto seu banco de dados é escrito e o modelo geralmente trabalha enquanto ele está aberto. stage_crate pode rodar a qualquer momento; apply_changes recusa enquanto o Serato está rodando. Inicie o Serato depois e as novas crates aparecem em poucos segundos.

O que uma escrita faz: cria novas crates no nível superior da Biblioteca Serato, em root.sqlite, e nada mais. Nunca altera ou exclui uma crate existente, nunca edita uma faixa, nunca toca em master.sqlite, database V2 ou na pasta Subcrates — o Serato regenera esses por conta própria.

Antes de cada escrita, ambos os bancos de dados são copiados em <state-dir>/backups/<library-id>/<timestamp>/ (diretório de estado padrão: ~/Library/Application Support/serato-dj-mcp), e os últimos dez são mantidos. Um backup é feito em cada tentativa de apply_changes que atinge a etapa de backup, incluindo tentativas que são então recusadas dentro da transação (um conflito de nome, por exemplo) — então "os últimos dez" significa as últimas dez tentativas, não dez escritas bem-sucedidas, e a mais recente pode já conter a escrita que você está tentando desfazer.

Não há ferramenta de desfazer. Para desfazer uma escrita específica, primeiro encontre o backup certo: use o backup_paths retornado por aquela chamada de apply_changes, ou abra <state-dir>/manifests/<library-id>.jsonl e pegue o backup_paths da linha cujo "commit_state" é "committed". <library-id> é o uuid relatado por list_libraries. Então, com esse par de caminhos em mãos:

1. Saia do Serato.
2. Na pasta da biblioteca, exclua root.sqlite-journal se presente, e exclua master.sqlite-wal e master.sqlite-shm.
3. Copie o root.sqlite e o master.sqlite do backup para a pasta da biblioteca, substituindo os atuais.
4. Exclua ~/Music/_Serato_/Subcrates/<crate name>.crate — o Serato o exportou depois de sincronizar a crate, e copiar os bancos de dados de volta não o remove.

Restaurar esses arquivos também reverte qualquer coisa que o próprio Serato registrou na biblioteca depois que esse backup foi feito.

Crates aninhadas não são suportadas: uma crate criada dessa forma dentro de outra crate é excluída pelo Serato na próxima sincronização, então toda crate vai para o nível superior.

Privacidade

O mesmo, como uma política independente com o arquivo-fonte por trás de cada declaração: PRIVACY.md.

• Tudo roda no seu computador. O servidor é um processo local que seu cliente MCP inicia. Ele não envia telemetria, não tem analytics e não faz requisições de rede. O único outro programa que ele executa é ps, para verificar se o Serato está rodando antes de uma gravação.
• O que ele lê: Os bancos de dados da biblioteca do Serato, sempre somente leitura, exceto para apply_changes; com o audit_library do check_filesystem: true, os metadados de arquivo das suas faixas no disco.
• O que ele grava, e onde:
  • --cache-dir (padrão ~/Library/Caches/serato-dj-mcp) guarda uma cópia instantânea do seu banco de dados da biblioteca. Seguro excluir a qualquer momento.
  • --state-dir (padrão ~/Library/Application Support/serato-dj-mcp) guarda crates preparados, um manifesto de cada gravação, arquivos de bloqueio e backups dos seus bancos de dados da biblioteca. Usado apenas com --allow-writes. Excluí-lo exclui esses backups.
  • Com --allow-writes, apply_changes grava novos crates no root.sqlite do Serato.
• O que sai do seu computador depende do seu cliente MCP. Resultados de ferramentas — títulos de faixas, artistas, nomes de crates, caminhos de arquivos — vão para seu assistente e, a partir daí, para o provedor de modelo que o cliente usa. Caminhos de faixas sob sua pasta pessoal são encurtados para ~; list_libraries, run_sql e os caminhos de backup retornados por apply_changes são caminhos completos. Verifique a política de dados do seu cliente se isso for importante para você.

Limitações

Leia isto antes de decidir no que confiar.

• Serato DJ 3.x não é suportado. Ele é reconhecido e relatado como version: "3.x", mas nada o lê — ele armazena um database V2 binário em vez de SQLite. Nenhuma ferramenta retornará dados de uma biblioteca 3.x.
• As leituras passam por um instantâneo, então uma resposta reflete a biblioteca a partir do último instantâneo, não do instante atual. Um instantâneo é reutilizado por até dois segundos, então enquanto o Serato está gravando, uma resposta pode estar tão atrasada. Apenas o instantâneo atual de cada biblioteca é mantido em --cache-dir; os mais antigos são excluídos assim que um mais novo é publicado.
• Duas verificações de auditoria dependem de semânticas de coluna que este projeto não confirmou. stale lê is_stale e streaming_only lê third_party_type; ambos eram zero em todas as faixas da biblioteca de referência, então suas contagens são relatadas sem qualquer afirmação sobre o que significam.
• rating e o sinalizador de streaming são repassados sem interpretação. rating era NULL ou 0 em todas as 118 faixas da biblioteca de referência, então o topo da escala não é confirmado. Nenhum significado além do valor bruto da coluna é afirmado para o sinalizador de streaming.
• O bit 2 de analysis_flags é afirmado, embora o resto do campo não seja. Ele é lido como "o Serato executou sua própria análise" — não o mesmo que "tem um BPM", já que um BPM pode vir das tags do arquivo — e exposto como flags.analyzed, no qual search_tracks pode filtrar. Medido em 2026-09-06 em 118 faixas: 106 têm o bit 2 definido, das quais 104 têm um BPM; doze o têm limpo — seis efeitos sonoros e seis faixas cujo BPM veio das tags em vez da própria análise do Serato.
• A busca de texto livre não é a busca do Serato. O Serato normaliza texto com uma função que apenas seu próprio processo tem, então q corresponde tanto às colunas normalizadas quanto às brutas e pode diferir do que o aplicativo encontraria.
• Uma página obtida enquanto o Serato está gravando pode abranger dois instantâneos. A paginação é por conjunto de chaves, então ela continua da mesma posição na cópia mais nova e diz isso em warnings: snapshot_advanced; algumas linhas podem ser repetidas ou puladas na junção.
• A gravação de crates é nova e experimental. O protocolo de gravação foi elaborado contra uma biblioteca ao vivo do Serato DJ Lite 4.0.9, mas não foi testado em atualizações do Serato, em bibliotecas grandes ou em bibliotecas distribuídas em discos externos. Mantenha seus próprios backups também.
• As gravações são estreitas de propósito. apply_changes cria novos crates de nível superior e nada mais: sem crates aninhados, sem crates inteligentes, sem renomear, reordenar ou excluir crates, sem edições em faixas, pontos de cue ou outros metadados.
• Um crate só pode conter faixas do próprio disco da biblioteca. Faixas de streaming e faixas que vivem no armazenamento Serato de outro disco são recusadas por stage_crate, nomeando cada uma.
• O Serato deve estar fechado para aplicar e reiniciado para ver o resultado. Novos crates aparecem no Serato, e nas ferramentas de leitura deste servidor, apenas depois que o Serato iniciou e sincronizou.
• A preparação lê o banco de dados ao vivo do Serato. stage_crate lê root.sqlite enquanto o Serato pode estar rodando. Medido em 2026-09-16: três preparações de 50 faixas cada, de 8 a 41 ms cada, com nada no log do próprio Serato nesses segundos. Isso é evidência, não uma garantia — uma biblioteca mais movimentada, ou um Serato no meio de sua própria gravação, não foi testado.
• Não há ferramenta de desfazer. Desfazer uma gravação significa restaurar os backups manualmente, como descrito acima.

Princípios

O que este servidor garante sobre sua biblioteca e o que ele se recusa a fazer está declarado em PRINCIPLES.md — cada garantia com o código que a aplica e os testes que falhariam se ela deixasse de ser verdadeira.

Segurança

Por favor, relate vulnerabilidades em particular — veja SECURITY.md. Não abra uma questão pública para elas.

Contribuindo

Questões e pull requests são bem-vindos; comece com CONTRIBUTING.md. Mudanças são registradas em CHANGELOG.md.

Licença

MIT. Mantido por Venut Technologies.

Serato e Serato DJ são marcas registradas de seus respectivos proprietários. Este projeto é independente e não é afiliado, endossado ou apoiado pela Serato.