Genius CLI

A local Go CLI for searching Genius and downloading song lyrics without deploying the MCP server to Cloudflare Workers.

Overview

The original project is a Model Context Protocol server for Genius. This repository now also includes a native Go command line tool that runs locally and covers the same practical workflows:

• Search songs
• Fetch song metadata
• Scrape lyrics from Genius song pages
• Download lyrics as .txt or .json
• List an artist's songs

Genius does not return lyrics directly from its official API, so the CLI fetches the Genius song page and extracts lyrics from the HTML. It uses the official API when a bearer token is available, and falls back to Genius public web JSON endpoints for the core local download flow.

Install

Build the CLI:

go build -o bin/genius ./cmd/genius

On Windows PowerShell:

go build -o bin\genius.exe .\cmd\genius

Authentication

The download path works through Genius public web endpoints even without a token. If credentials are available, the CLI will use them for official API calls.

Credential discovery order:

1. --token
2. GENIUS_ACCESS_TOKEN, GENIUS_API_TOKEN, or GENIUS_API_KEY
3. --token-ref
4. --client-id and --client-secret
5. GENIUS_CLIENT_ID and GENIUS_CLIENT_SECRET
6. 1Password refs:
   • op://Personal/genius/client-id
   • op://Personal/genius/client-secret

You can override those refs:

genius --client-id-ref op://Vault/item/client-id --client-secret-ref op://Vault/item/client-secret doctor

Or skip 1Password entirely:

export GENIUS_CLIENT_ID="your-client-id"
export GENIUS_CLIENT_SECRET="your-client-secret"
genius doctor

On Windows PowerShell:

$env:GENIUS_CLIENT_ID = "your-client-id"
$env:GENIUS_CLIENT_SECRET = "your-client-secret"
.\bin\genius.exe doctor

The CLI never prints resolved secrets.

Usage

Search:

genius search "All My Life Lil Durk" --limit 5

Print lyrics by query:

genius lyrics "All My Life Lil Durk"

Print lyrics by Genius song ID:

genius lyrics 9042595

Download lyrics as text:

genius download "All My Life Lil Durk" --out lyrics

Download full metadata and lyrics as JSON:

genius download 9042595 --format json --out lyrics

Fetch song metadata:

genius song 9042595

List artist songs:

genius artist-songs 21964 --sort popularity --per-page 20

Check connectivity, auth discovery, and lyrics scraping:

genius doctor

MCP Worker

The original Cloudflare Worker MCP server remains in src/. To run it locally:

npm install
npm run dev

To deploy the worker:

npm run deploy

License

[Add your license here]

Contributing

[Add contribution guidelines here]

Support

For issues and questions:

• Open an issue on GitHub
• Check the Genius API documentation
• Review the MCP documentation