Serato DJ MCP (serato-dj-mcp)

serato-dj-mcp

Pregúntale a Claude sobre tu biblioteca de Serato DJ: encuentra pistas que mezclen armónicamente por BPM y clave Camelot, explora tus crates, audita la biblioteca en busca de duplicados y archivos faltantes, y haz que se creen nuevos crates para ti, mostrándotelos antes de escribir nada. Funciona a través del Model Context Protocol (MCP), la forma estándar en que aplicaciones de IA como Claude Desktop, Claude Code, Cursor y VS Code se conectan a herramientas en tu computadora: este es un pequeño servidor local que responde desde tu biblioteca y no envía nada a ningún lugar por sí mismo.

Estado: experimental. Pre-1.0 y en desarrollo activo: una versión menor puede cambiar el comportamiento o romper la compatibilidad, un parche nunca lo hace.

[!IMPORTANT] No está afiliado, respaldado ni soportado por Serato. Serato y Serato DJ son marcas comerciales de sus respectivos propietarios. Este proyecto lee un diseño de base de datos de ingeniería inversa y puede dejar de funcionar después de cualquier actualización de Serato.

Lo que puedes preguntar

Una vez que el servidor está conectado, hablas con tu asistente como de costumbre:

• "Encuentra pistas entre 122 y 126 BPM en 8A o 9A que haya añadido este año."
• "Dame pistas que mezclen armónicamente desde 8A, alrededor de 124 BPM."
• "Muéstrame lo que hay en mi crate Warm Up, en orden."
• "Audita mi biblioteca: duplicados, archivos faltantes, pistas que no están en ningún crate."
• "¿Qué pistas de mi biblioteca no tienen BPM o no tienen clave?"

Con la escritura de crates activada:

• "Crea un crate llamado Friday Opening con las veinte pistas que acabas de encontrar, y muéstrame la lista antes de escribir nada." Luego, una vez que hayas cerrado Serato: "Aplica el crate preparado."

El asistente hace la búsqueda; el servidor responde desde tu biblioteca y, cuando se le pide, escribe solo lo que aprobaste.

Instalación

Funciona en macOS. Probado con Serato DJ Lite 4.0.9 en macOS; la suite de pruebas se ejecuta en CI en macOS y Linux con Node.js 22.16 y 24. Windows no está probado — consulta Compatibilidad. La extensión de Claude Desktop y la configuración de Claude Code a continuación se probaron manualmente en macOS; las configuraciones de Cursor y VS Code siguen la documentación de esos editores y no se han probado.

Cada configuración inicia el servidor en modo solo lectura. La escritura de crates es un interruptor separado, descrito a continuación.

Claude Desktop

Como extensión (sin necesidad de Node.js). Descarga serato-dj-mcp-<version>.mcpb desde la última versión (adjunta desde la versión 0.1.1 en adelante) y ábrela; Claude Desktop muestra lo que contiene y la instala. Su configuración te permite apuntar a una carpeta de biblioteca y activar la escritura de crates o SQL sin procesar; los tres pueden quedarse como están.

O manualmente, con Node.js 22.16 o más reciente instalado: abre Configuración → Desarrollador → Editar configuración y añade el servidor a claude_desktop_config.json, luego reinicia Claude Desktop.

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

Claude Code

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

Añade --scope user antes de serato para tenerlo en cada proyecto. El repositorio también es un plugin de Claude Code que inicia el mismo comando.

Cursor

Añadir a Cursor, o añade la misma entrada mcpServers que para Claude Desktop a ~/.cursor/mcp.json. El enlace abre cursor://anysphere.cursor-deeplink/mcp/install?name=serato&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcmF0by1kai1tY3AiXX0=, que le pide a Cursor que añada {"command":"npx","args":["-y","serato-dj-mcp"]} bajo el nombre serato.

VS Code

Instalar en VS Code, o desde una terminal:

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

Opciones para cualquier cliente

Añade opciones después de serato-dj-mcp en args, por ejemplo "args": ["-y", "serato-dj-mcp", "--allow-writes"]:

• --library <path> — la carpeta de la biblioteca de Serato (la que contiene master.sqlite). No es necesaria en macOS, donde la biblioteca en ~/Library/Application Support/Serato y en unidades montadas se encuentra automáticamente.
• --allow-writes — escritura de crates, ver más abajo.
• --allow-raw-sql — añade run_sql, SQL de solo lectura para desarrolladores.

Todas las opciones están listadas en Opciones.

node:sqlite es una API de Node experimental e imprime una advertencia en stderr; eso es esperado e inofensivo, porque el protocolo MCP viaja por stdout.

Desde el código fuente, para desarrolladores

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

Luego usa "command": "node" con "args": ["/absolute/path/to/serato-dj-mcp/dist/index.js"], o claude mcp add serato -- node /absolute/path/to/serato-dj-mcp/dist/index.js.

Lo que el servidor lee, escribe y envía está en PRIVACY.md: no hace solicitudes de red y no tiene telemetría.

Compatibilidad

Serato DJ 4.x	Compatible. Desarrollado y probado contra Serato DJ Lite 4.0.9 (esquema de biblioteca 202). Otras versiones de esquema 4.x se leen con una advertencia schema_unknown. Se espera que Serato DJ Pro 4.x use el mismo formato de biblioteca pero no se ha probado.
Serato DJ 3.x	Detectado e informado, no leído (mantiene un database V2 binario en lugar de SQLite).
macOS	Compatible. Aquí es donde se desarrolla el proyecto, y CI se ejecuta en él.
Windows	Sin probar. El servidor no tiene manejo específico para Windows: pasa --library explícitamente, porque la detección automática solo conoce el diseño de macOS, y espera directorios de caché y estado al estilo macOS bajo tu carpeta de usuario. La verificación de "¿Serato está ejecutándose?" usa ps, que Windows no tiene, por lo que apply_changes puede negarse a escribir en lugar de adivinar.
Linux	Serato no se ejecuta en Linux; la suite de pruebas se ejecuta allí en CI con fixtures sintéticos.
Node.js	22.16 o más reciente, porque backup() de node:sqlite llega allí. No se asume: CI ejecuta toda la suite en 22.16 y en 24, en macOS y en Ubuntu.
Extensión de Claude Desktop	Se ejecuta en el propio Node.js de Claude Desktop, no en el tuyo. Verificada manualmente el 2026-09-24 con Claude Desktop 2.7032.0 en macOS, cuyo Node.js integrado es 24.21: instalada, luego list_libraries y list_crates respondieron con los datos de la biblioteca.

Todo lo que este servidor asume sobre la biblioteca de Serato está documentado en docs/serato-4x-notes.md, con la medición detrás de cada afirmación.

Solo lectura por defecto, escritura bajo petición

Por defecto, el servidor nunca escribe en los archivos de Serato. Cada lectura pasa por una copia instantánea de la base de datos de la biblioteca en --cache-dir, por lo que una pregunta del asistente no puede cambiar tu biblioteca, ya sea que Serato esté abierto o no.

Dos banderas amplían eso, y cada una registra herramientas adicionales solo cuando se le da — una herramienta que no existe no puede ser llamada por error:

• --allow-raw-sql añade run_sql: SELECT de solo lectura contra la instantánea, devolviendo filas sin procesar.
• --allow-writes añade stage_crate, preview_changes, apply_changes y discard_changes. La escritura se divide en dos: los crates se preparan primero, lo que nunca toca la biblioteca, y se aplican solo cuando confirmas y Serato está cerrado. Ambas bases de datos se respaldan antes de cada escritura. Los detalles están en Escritura en la biblioteca.

Herramientas

• list_libraries — las bibliotecas que este servidor puede ver, con versión, versión de esquema y ubicaciones. Las rutas aquí no están redactadas, por lo que puedes copiar una en --library.
• search_tracks — búsqueda por texto libre, BPM, clave, género, calificación, fecha de adición, membresía de crate y banderas. La tonalidad es Camelot; una pista cuya clave Serato mismo no pudo analizar aún se empareja, y key_source dice de dónde vino la clave. Paginado con un cursor opaco; la página predeterminada es de 25 pistas y nueve campos.
• get_tracks — obtiene pistas por los ids search_tracks devueltos. Los ids desconocidos vuelven en missing en lugar de descartarse.
• list_crates — los crates en el espacio de la Biblioteca de Serato, con su ruta de visualización y cuántas pistas distintas contiene cada uno. Los crates inteligentes, las raíces de espacio y otros espacios internos de Serato (como el panel Prepare) no se listan.
• get_crate_tracks — las pistas de un crate, en el orden propio del crate. Solo se pueden dar crates en el espacio de la Biblioteca de Serato.
• audit_library — diagnostica la biblioteca. Cada verificación se ejecuta por defecto e informa un conteo más hasta diez ids de pista de ejemplo: pistas sin BPM, sin clave alguna, con una clave que Serato mismo no puede mostrar, marcadas como obsoletas, en ningún crate, solo de streaming, duplicadas y con rutas rotas. duplicates informa grupos en lugar de ids sueltos, porque qué pista duplica a cuál es la parte sobre la que puedes actuar. broken_paths lee la bandera de faltante propia de Serato por defecto; pasa check_filesystem: true para también mirar en disco, lo cual es opcional porque un stat contra una unidad desconectada bloquea durante segundos. Una unidad que no está montada se informa como tal en lugar de declarar todas sus pistas como faltantes.
• run_sql — un SELECT de solo lectura contra una copia instantánea. Se registra solo con --allow-raw-sql, porque devuelve filas sin procesar sin redacción de rutas.

Con --allow-writes:

• stage_crate — prepara un nuevo crate a partir de ids de pista. Nada se escribe aún; la respuesta lista cada pista preparada por título y artista, así que revísala.
• preview_changes — muestra lo que está preparado, con format: "detail" hasta cada pista.
• apply_changes — escribe todo lo preparado, todo o nada. Se rechaza mientras Serato está ejecutándose.
• discard_changes — elimina un crate preparado, o todos ellos.

Opciones

--library <path>, --root <dir> (repetible), --cache-dir <dir>, --state-dir <dir>, --allow-raw-sql, --allow-writes, --help, --version. SERATO_LIBRARY_PATH es una alternativa a --library; la bandera gana. Una opción desconocida es un error, no un no-op.

Escritura en la biblioteca

Las escrituras necesitan --allow-writes y ocurren en dos pasos, porque Serato debe estar cerrado mientras se escribe su base de datos y el modelo generalmente trabaja mientras está abierto. stage_crate puede ejecutarse en cualquier momento; apply_changes se rechaza mientras Serato está ejecutándose. Inicia Serato después y los nuevos crates aparecen en unos segundos.

Lo que hace una escritura: crea nuevos crates en el nivel superior de la Biblioteca de Serato, en root.sqlite, y nada más. Nunca cambia ni elimina un crate existente, nunca edita una pista, nunca toca master.sqlite, database V2 ni la carpeta Subcrates — Serato regenera esos por sí mismo.

Antes de cada escritura, ambas bases de datos se respaldan bajo <state-dir>/backups/<library-id>/<timestamp>/ (directorio de estado predeterminado: ~/Library/Application Support/serato-dj-mcp), y se conservan las últimas diez. Se toma un respaldo en cada intento de apply_changes que llega al paso de respaldo, incluidos los intentos que luego se rechazan dentro de la transacción (un conflicto de nombre, por ejemplo) — así que "las últimas diez" significa los últimos diez intentos, no diez escrituras exitosas, y la más reciente puede que ya contenga la escritura que estás tratando de deshacer.

No hay herramienta de deshacer. Para deshacer una escritura específica, primero encuentra el respaldo correcto: usa el backup_paths devuelto por esa llamada a apply_changes, o abre <state-dir>/manifests/<library-id>.jsonl y toma el backup_paths de la línea cuyo "commit_state" es "committed". <library-id> es el uuid informado por list_libraries. Luego, con ese par de rutas en mano:

1. Cierra Serato.
2. En la carpeta de la biblioteca, elimina root.sqlite-journal si está presente, y elimina master.sqlite-wal y master.sqlite-shm.
3. Copia el root.sqlite y master.sqlite respaldados en la carpeta de la biblioteca, reemplazando los actuales.
4. Elimina ~/Music/_Serato_/Subcrates/<crate name>.crate — Serato lo exportó después de sincronizar el crate, y copiar las bases de datos de vuelta no lo elimina.

Restaurar estos archivos también revierte cualquier cosa que Serato mismo registró en la biblioteca después de que se tomó ese respaldo.

Los crates anidados no son compatibles: un crate creado de esta manera dentro de otro crate es eliminado por Serato en su próxima sincronización, por lo que cada crate va al nivel superior.

Privacidad

Lo mismo, como una política independiente con el archivo fuente detrás de cada declaración: PRIVACY.md.

• Todo se ejecuta en tu computadora. El servidor es un proceso local que tu cliente MCP inicia. No envía telemetría, no tiene analíticas y no realiza solicitudes de red. El único otro programa que ejecuta es ps, para verificar si Serato está en ejecución antes de una escritura.
• Lo que lee: Las bases de datos de la biblioteca de Serato, siempre de solo lectura excepto para apply_changes; con audit_library's check_filesystem: true, los metadatos de archivo de tus pistas en disco.
• Lo que escribe, y dónde:
  • --cache-dir (por defecto ~/Library/Caches/serato-dj-mcp) contiene una copia instantánea de tu base de datos de biblioteca. Seguro de eliminar en cualquier momento.
  • --state-dir (por defecto ~/Library/Application Support/serato-dj-mcp) contiene crates preparados, un manifiesto de cada escritura, archivos de bloqueo y copias de seguridad de tus bases de datos de biblioteca. Solo se usa con --allow-writes. Eliminarlo elimina esas copias de seguridad.
  • Con --allow-writes, apply_changes escribe nuevos crates en root.sqlite de Serato.
• Lo que sale de tu computadora depende de tu cliente MCP. Los resultados de las herramientas — títulos de pistas, artistas, nombres de crates, rutas de archivos — van a tu asistente, y desde allí al proveedor de modelos que use el cliente. Las rutas de pistas bajo tu carpeta de inicio se acortan a ~; list_libraries, run_sql y las rutas de copia de seguridad devueltas por apply_changes son rutas completas. Revisa la política de datos de tu cliente si eso te importa.

Limitaciones

Lee esto antes de decidir qué confiar.

• Serato DJ 3.x no es compatible. Se reconoce y se informa como version: "3.x", pero nada lo lee — almacena un database V2 binario en lugar de SQLite. Ninguna herramienta devolverá datos de una biblioteca 3.x.
• Las lecturas pasan por una instantánea, por lo que una respuesta refleja la biblioteca a partir de la última instantánea, no del instante actual. Una instantánea se reutiliza hasta por dos segundos, por lo que mientras Serato está escribiendo, una respuesta puede estar tan atrasada. Solo se mantiene la instantánea actual de cada biblioteca en --cache-dir; las más antiguas se eliminan tan pronto como se publica una más nueva.
• Dos comprobaciones de auditoría se basan en semánticas de columnas que este proyecto no ha confirmado. stale lee is_stale y streaming_only lee third_party_type; ambos eran cero en cada pista de la biblioteca de referencia, por lo que sus conteos se informan sin afirmar qué significan.
• rating y el indicador de streaming se pasan sin interpretar. rating era NULL o 0 en las 118 pistas de la biblioteca de referencia, por lo que la parte superior de la escala no está confirmada. No se afirma ningún significado más allá del valor bruto de la columna para el indicador de streaming.
• Se afirma el bit 2 de analysis_flags, aunque el resto del campo no. Se lee como "Serato ejecutó su propio análisis" — no lo mismo que "tiene un BPM", ya que un BPM puede provenir de las etiquetas del archivo — y se expone como flags.analyzed, que search_tracks puede filtrar. Medido el 2026-09-06 en 118 pistas: 106 tienen el bit 2 establecido, de las cuales 104 tienen un BPM; doce lo tienen claro — seis efectos de sonido y seis pistas cuyo BPM provino de etiquetas en lugar del propio análisis de Serato.
• La búsqueda de texto libre no es la búsqueda de Serato. Serato normaliza el texto con una función que solo su propio proceso tiene, por lo que q coincide tanto con las columnas normalizadas como con las brutas y puede diferir de lo que la aplicación encontraría.
• Una página tomada mientras Serato está escribiendo puede abarcar dos instantáneas. La paginación es por claves, por lo que continúa desde la misma posición en la copia más nueva y lo indica en warnings: snapshot_advanced; algunas filas pueden repetirse u omitirse en la unión.
• La escritura de crates es nueva y experimental. El protocolo de escritura se elaboró contra una biblioteca en vivo de Serato DJ Lite 4.0.9, pero no se ha probado en actualizaciones de Serato, en bibliotecas grandes, ni en bibliotecas distribuidas en discos externos. Mantén también tus propias copias de seguridad.
• Las escrituras son limitadas a propósito. apply_changes crea nuevos crates de nivel superior y nada más: sin crates anidados, sin crates inteligentes, sin renombrar, reordenar o eliminar crates, sin ediciones a pistas, puntos de referencia u otros metadatos.
• Un crate solo puede contener pistas del propio disco de la biblioteca. Las pistas de streaming, y las pistas que viven en el almacén de Serato de otro disco, son rechazadas por stage_crate, nombrando cada una.
• Serato debe estar cerrado para aplicar, y reiniciado para ver el resultado. Los nuevos crates aparecen en Serato, y en las herramientas de lectura de este servidor, solo después de que Serato haya iniciado y sincronizado.
• La preparación lee la base de datos en vivo de Serato. stage_crate lee root.sqlite mientras Serato puede estar en ejecución. Medido el 2026-09-16: tres preparaciones de 50 pistas cada una, de 8 a 41 ms cada una, con nada en el propio registro de Serato durante esos segundos. Eso es evidencia, no una garantía — una biblioteca más ocupada, o un Serato en medio de su propia escritura, no se ha probado.
• No hay herramienta de deshacer. Deshacer una escritura significa restaurar las copias de seguridad manualmente, como se describe arriba.

Principios

Lo que este servidor garantiza sobre tu biblioteca, y lo que se niega a hacer, se establece en PRINCIPLES.md — cada garantía con el código que la aplica y las pruebas que fallarían si dejara de ser verdad.

Seguridad

Por favor, informa vulnerabilidades de forma privada — consulta SECURITY.md. No abras un problema público para ellas.

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas; comienza con CONTRIBUTING.md. Los cambios se registran en CHANGELOG.md.

Licencia

MIT. Mantenido por Venut Technologies.

Serato y Serato DJ son marcas comerciales de sus respectivos propietarios. Este proyecto es independiente y no está afiliado, respaldado ni apoyado por Serato.