Servidor MCP Genius | Awesome MCP Servers

Genius MCP Server

Um servidor MCP que traz o poder do Genius para o seu assistente de IA.

Consulte músicas, artistas, anotações de letras, anotações de artes de álbum, relacionamentos entre músicas, créditos e conhecimento editorial por meio de um conjunto limpo de ferramentas e prompts — alimentado tanto pela API oficial do Genius quanto pela biblioteca Python lyricsgenius.

O que ele faz

O Genius MCP Server expõe a base de conhecimento do Genius.com a qualquer cliente de IA compatível com MCP (Claude Desktop, Claude Code, Cursor, etc.). Ele permite que a IA:

Pesquise músicas e artistas por nome
Busque metadados completos da música — título, álbum, data de lançamento, estado da letra e descrições editoriais do Genius
Busque perfis de artistas — biografia, número de seguidores, status de verificação
Navegue pela discografia de um artista — ordenada por popularidade ou data de lançamento, ou como uma lista completa de álbuns com listas de faixas
Leia anotações — explicações da comunidade e verificadas pelo artista sobre fragmentos específicos de letras, cada uma marcada com um nível de confiança para que a IA saiba qual peso atribuir a elas
Leia anotações de artes de álbum — explicações da comunidade sobre elementos visuais, simbolismo e escolhas artísticas escritas diretamente nas imagens das capas dos álbuns
Explore relacionamentos entre músicas — descubra o que uma música sampleia, interpola, regrava, remixa ou traduz, e quais músicas posteriores a samplearam por sua vez
Consulte créditos de músicas — compositores, produtores, artistas participantes e funções de performance personalizadas (engenheiro de mixagem, estúdio de gravação, gravadora)
Execute prompts de análise pré-construídos que reúnem todos os dados relevantes de uma só vez e pedem à IA uma análise aprofundada de uma música ou artista

Ferramentas

Algumas ferramentas chamam a API oficial do Genius (api.genius.com) usando seu token de acesso. Outras usam a biblioteca Python lyricsgenius, que acessa a API pública não documentada do Genius — esses endpoints não fazem parte do contrato oficial da API e podem mudar sem aviso prévio.

Ferramenta	Descrição	Backend
`search_song`	Pesquisa no Genius por músicas que correspondam a uma consulta. Retorna IDs de músicas, títulos, artistas e contagens de anotações.	API oficial
`get_song_details`	Busca metadados completos e descrição editorial de uma música pelo seu ID no Genius.	API oficial
`get_song_annotations`	Busca todas as anotações de uma música, opcionalmente filtradas por nível de confiança (`artist_verified`, `accepted`, `unreviewed`).	API oficial
`get_annotation_detail`	Busca o texto completo e os metadados de uma única anotação pelo seu ID.	API oficial
`get_song_questions_and_answers`	Busca perguntas e respostas enviadas por usuários para uma música, com paginação. Apenas perguntas que possuem uma resposta aceita são retornadas.	`lyricsgenius` (API pública não documentada)
`get_song_relationships`	Busca os relacionamentos musicais de uma música — o que ela sampleia, interpola, regrava, remixa ou traduz, e quais músicas posteriores a samplearam ou regravaram. Apenas tipos de relacionamento com pelo menos uma música vinculada são retornados.	API oficial
`get_song_credits`	Busca créditos de composição e produção de uma música: compositores, produtores, artistas participantes e funções de performance personalizadas (ex.: engenheiro de mixagem, estúdio de gravação, gravadora).	API oficial
`search_artist`	Pesquisa no Genius por um artista pelo nome. Retorna IDs de artistas e informações básicas de perfil.	API oficial
`get_artist_details`	Busca perfil completo e biografia editorial de um artista pelo seu ID no Genius.	API oficial
`get_artist_songs`	Lista músicas de um artista, ordenáveis por `popularity` ou `release_date`, com paginação.	API oficial
`get_artist_albums`	Recupera a discografia completa de um artista como uma lista paginada de álbuns com IDs de álbuns.	`lyricsgenius` (API pública não documentada)
`search_album`	Pesquisa no Genius por álbuns que correspondam a uma consulta. Retorna IDs de álbuns, nomes, nomes de artistas e datas de lançamento.	`lyricsgenius` (API pública não documentada)
`get_album_details`	Busca metadados, lista de faixas completa em ordem e lista de artes de capa de um álbum pelo seu ID de álbum no Genius. Cada faixa inclui seu ID de música para encadeamento com outras ferramentas. A primeira arte de capa é sempre a capa principal do álbum; artes anotadas incluem um `annotation_id`.	API oficial + `lyricsgenius`
`get_cover_art_annotations`	Busca a anotação completa escrita em uma imagem específica de arte de capa de álbum — texto do corpo, nível de confiança, autores e contagem de votos. Requer `cover_art_id` e `album_id` (ambos disponíveis em `get_album_details`). Chame apenas para artes de capa que tenham um `annotation_id`.	`lyricsgenius` (API pública não documentada)

Prompts

Prompts são fluxos de trabalho multi-etapas pré-construídos que coletam dados do Genius e os alimentam à IA em um contexto estruturado.

`analyze-song`

Argumentos: song_title (obrigatório), artist_name (opcional)

Pesquisa a música, busca seus metadados completos e descrição editorial, recupera todas as anotações (ordenadas por nível de confiança) e pede à IA uma análise aprofundada do significado da música, seus temas e contexto cultural.

`artist-deep-dive`

Argumentos: artist_name (obrigatório)

Busca a biografia completa do artista, suas 3 músicas mais populares com metadados e anotações verificadas pelo artista (quando disponíveis), e pede à IA uma visão geral dos temas, estilo e importância do artista.

Começando

1. Obtenha um token da API do Genius

Acesse https://genius.com/api-clients e faça login.
Crie um novo cliente de API.
Copie o Client Access Token — este é o valor que você usará para GENIUS_ACCESS_TOKEN.

2. Configure as variáveis de ambiente

Copie o arquivo de exemplo e preencha com seu token:

cp .env.example .env

Edite o .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. Execute com Python

Requisitos: Python 3.11+

Instale as dependências:

pip install -r requirements.txt

Execute o servidor:

python main.py

O servidor iniciará em http://127.0.0.1:8080 (modo HTTP transmissível) ou no modo stdio, dependendo da sua configuração de STREAMABLE_HTTP.

4. Execute com Docker

Modo HTTP transmissível (padrão):

docker compose up --build

O servidor é executado como genius-mcp-server na porta 8080. O arquivo .env é montado no contêiner — certifique-se de que ele exista e contenha seu token antes de iniciar.

Modo stdio (ex.: para Claude Desktop via Docker):

Defina STREAMABLE_HTTP=false no seu .env e execute:

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

Modos de transporte

Modo	`STREAMABLE_HTTP`	Caso de uso
HTTP transmissível	`true` (padrão)	Claude Code, clientes MCP remotos, ferramentas baseadas na web
stdio	`false`	Claude Desktop, integrações locais de CLI

Conectando-se a um cliente MCP

Claude Code (HTTP transmissível)

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

Claude Desktop (stdio)

Com STREAMABLE_HTTP=false no seu .env, adicione isto ao seu 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"
      }
    }
  }
}

Níveis de confiança das anotações

Toda anotação retornada pelo servidor inclui um campo trust_level. Isso permite que a IA raciocine sobre a confiabilidade da fonte:

Nível de confiança	Significado
`artist_verified`	Escrito ou confirmado pelo artista. Trate como verdade absoluta.
`accepted`	Revisado e aprovado pela equipe editorial do Genius. Alta qualidade.
`unreviewed`	Enviado por usuários da comunidade, ainda não revisado. Trate como interpretação.

A ferramenta get_song_annotations aceita um argumento filter para recuperar apenas anotações em um nível de confiança específico.

Estrutura do projeto

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

Licença

MIT

Genius MCP Server

Documentação

Genius MCP Server

Índice

O que ele faz

Ferramentas

Prompts

analyze-song

artist-deep-dive

Começando

1. Obtenha um token da API do Genius

2. Configure as variáveis de ambiente

3. Execute com Python

4. Execute com Docker

Modos de transporte

Conectando-se a um cliente MCP

Claude Code (HTTP transmissível)

Claude Desktop (stdio)

Níveis de confiança das anotações

Estrutura do projeto

Licença

`analyze-song`

`artist-deep-dive`