Genius MCP Server

---

Tabla de Contenidos

• Qué hace
• Herramientas
• Prompts
• Primeros pasos
  • 1. Obtén un token de API de Genius
  • 2. Configura las variables de entorno
  • 3. Ejecuta con Python
  • 4. Ejecuta con Docker
• Modos de transporte
• Conexión a un cliente MCP
• Niveles de confianza de anotaciones
• Estructura del proyecto
• Licencia

---

Qué hace

El servidor Genius MCP expone la base de conocimiento de Genius.com a cualquier cliente de IA compatible con MCP (Claude Desktop, Claude Code, Cursor, etc.). Permite que la IA:

• Buscar canciones y artistas por nombre
• Obtener metadatos completos de la canción — título, álbum, fecha de lanzamiento, estado de la letra y descripciones editoriales de Genius
• Obtener perfiles de artistas — biografía, número de seguidores, estado de verificación
• Explorar la discografía de un artista — ordenada por popularidad o fecha de lanzamiento, o como una lista completa de álbumes con listas de canciones
• Leer anotaciones — explicaciones de la comunidad y verificadas por artistas de fragmentos específicos de letras, cada una etiquetada con un nivel de confianza para que la IA sepa cuánto peso darles
• Leer anotaciones de portadas de álbumes — explicaciones de la comunidad sobre elementos visuales, simbolismo y elecciones artísticas escritas directamente en las imágenes de las portadas de los álbumes
• Explorar relaciones entre canciones — descubre qué samplea, interpola, versiona o remezcla una canción, y qué canciones posteriores la samplearon a su vez
• Consultar créditos de canciones — escritores, productores, artistas invitados y roles de interpretación personalizados (ingeniero de mezcla, estudio de grabación, sello)
• Ejecutar prompts de análisis predefinidos que recopilan todos los datos relevantes de una sola vez y piden a la IA un análisis profundo de una canción o artista

---

Herramientas

Algunas herramientas llaman a la API oficial de Genius (api.genius.com) usando tu token de acceso. Otras usan la biblioteca de Python lyricsgenius, que accede a la API pública no documentada de Genius — estos endpoints no forman parte del contrato oficial de la API y pueden cambiar sin previo aviso.

Herramienta	Descripción	Backend
search_song	Busca en Genius canciones que coincidan con una consulta. Devuelve IDs de canciones, títulos, artistas y recuentos de anotaciones.	API oficial
get_song_details	Obtiene metadatos completos y descripción editorial de una canción por su ID de Genius.	API oficial
get_song_annotations	Obtiene todas las anotaciones de una canción, opcionalmente filtradas por nivel de confianza (artist_verified, accepted, unreviewed).	API oficial
get_annotation_detail	Obtiene el texto completo y los metadatos de una sola anotación por su ID.	API oficial
get_song_questions_and_answers	Obtiene preguntas y respuestas enviadas por usuarios para una canción, con paginación. Solo se devuelven preguntas que tienen una respuesta aceptada.	lyricsgenius (API pública no documentada)
get_song_relationships	Obtiene las relaciones musicales de una canción — qué samplea, interpola, versiona, remezcla o traduce, y qué canciones posteriores la samplearon o versionaron. Solo se devuelven los tipos de relación con al menos una canción vinculada.	API oficial
get_song_credits	Obtiene los créditos de escritura y producción de una canción: escritores, productores, artistas invitados y roles de interpretación personalizados (por ejemplo, ingeniero de mezcla, estudio de grabación, sello).	API oficial
search_artist	Busca en Genius un artista por nombre. Devuelve IDs de artistas e información básica del perfil.	API oficial
get_artist_details	Obtiene el perfil completo y la biografía editorial de un artista por su ID de Genius.	API oficial
get_artist_songs	Lista canciones de un artista, ordenables por popularity o release_date, con paginación.	API oficial
get_artist_albums	Recupera la discografía completa de un artista como una lista paginada de álbumes con IDs de álbumes.	lyricsgenius (API pública no documentada)
search_album	Busca en Genius álbumes que coincidan con una consulta. Devuelve IDs de álbumes, nombres, nombres de artistas y fechas de lanzamiento.	lyricsgenius (API pública no documentada)
get_album_details	Obtiene metadatos, lista de canciones completa y ordenada, y lista de portadas para un álbum por su ID de álbum de Genius. Cada pista incluye su ID de canción para encadenar con otras herramientas. La primera portada es siempre la portada principal del álbum; las obras anotadas incluyen un annotation_id.	API oficial + lyricsgenius
get_cover_art_annotations	Obtiene la anotación completa escrita en una imagen específica de portada de álbum — texto del cuerpo, nivel de confianza, autores y recuento de votos. Requiere cover_art_id y album_id (ambos disponibles desde get_album_details). Solo llama para portadas que tengan un annotation_id.	lyricsgenius (API pública no documentada)

---

Prompts

Los prompts son flujos de trabajo predefinidos de varios pasos que recopilan datos de Genius y los alimentan a la IA en un contexto estructurado.

analyze-song

Argumentos: song_title (obligatorio), artist_name (opcional)

Busca la canción, obtiene sus metadatos completos y descripción editorial, recupera todas las anotaciones (ordenadas por nivel de confianza) y pide a la IA un análisis profundo del significado, los temas y el contexto cultural de la canción.

artist-deep-dive

Argumentos: artist_name (obligatorio)

Obtiene la biografía completa del artista, sus 3 canciones más populares con metadatos y anotaciones verificadas por el artista (cuando estén disponibles), y pide a la IA una visión general de los temas, el estilo y la importancia del artista.

---

Primeros pasos

1. Obtén un token de API de Genius

1. Ve a https://genius.com/api-clients e inicia sesión.
2. Crea un nuevo cliente de API.
3. Copia el Token de acceso de cliente — este es el valor que usarás para GENIUS_ACCESS_TOKEN.

2. Configura las variables de entorno

Copia el archivo de entorno de ejemplo y completa tu token:

cp .env.example .env

Edita .env:

# Required — your Genius API access token
GENIUS_ACCESS_TOKEN=your_token_here

# Transport mode:
# true  → run as a Streamable HTTP server on port 8080
# false → run in stdio mode (for Claude Desktop)
STREAMABLE_HTTP=true

3. Ejecuta con Python

Requisitos: Python 3.11+

Instala las dependencias:

pip install -r requirements.txt

Ejecuta el servidor:

python main.py

El servidor se iniciará en http://127.0.0.1:8080 (modo Streamable HTTP) o en modo stdio según tu configuración de STREAMABLE_HTTP.

4. Ejecuta con Docker

Modo Streamable HTTP (predeterminado):

docker compose up --build

El servidor se ejecuta como genius-mcp-server en el puerto 8080. El archivo .env se monta en el contenedor — asegúrate de que exista y contenga tu token antes de iniciar.

Modo stdio (por ejemplo, para Claude Desktop a través de Docker):

Configura STREAMABLE_HTTP=false en tu .env, luego ejecuta:

docker run --rm -i --env-file .env $(docker build -q .)

---

Modos de transporte

Modo	STREAMABLE_HTTP	Caso de uso
Streamable HTTP	true (predeterminado)	Claude Code, clientes MCP remotos, herramientas basadas en web
stdio	false	Claude Desktop, integraciones CLI locales

---

Conexión a un cliente MCP

Claude Code (Streamable HTTP)

claude mcp add genius --transport http http://127.0.0.1:8080/mcp

Claude Desktop (stdio)

Con STREAMABLE_HTTP=false en tu .env, agrega esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "genius": {
      "command": "python",
      "args": ["/absolute/path/to/genius-mcp/main.py"],
      "env": {
        "GENIUS_ACCESS_TOKEN": "your_token_here",
        "STREAMABLE_HTTP": "false"
      }
    }
  }
}

---

Niveles de confianza de anotaciones

Cada anotación devuelta por el servidor incluye un campo trust_level. Esto permite que la IA razone sobre la confiabilidad de la fuente:

Nivel de confianza	Significado
artist_verified	Escrito o confirmado por el artista. Trátalo como verdad absoluta.
accepted	Revisado y aprobado por el personal editorial de Genius. Alta calidad.
unreviewed	Enviado por usuarios de la comunidad, aún no revisado. Trátalo como interpretación.

La herramienta get_song_annotations acepta un argumento filter para recuperar solo anotaciones en un nivel de confianza específico.

---

Estructura del proyecto

genius-mcp/
├── main.py                    # Entry point — configures transport and starts the server
├── app.py                     # FastMCP app instance
├── mcp_components/
│   ├── genius_api.py          # Async HTTP client for the Genius API
│   ├── mcp_tools.py           # MCP tool definitions
│   └── mcp_prompts.py         # MCP prompt definitions
├── tests/
│   ├── test_mcp_server_initialization.py
│   └── test_mcp_server_tools.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .env.example

---

Licencia

MIT