genius-mcp

Table of Contents

• What It Does
• Tools
• Prompts
• Getting Started
  • 1. Get a Genius API Token
  • 2. Configure Environment Variables
  • 3. Run with Python
  • 4. Run with Docker
• Transport Modes
• Connecting to an MCP Client
• Annotation Trust Levels
• Project Structure
• License

What It Does

The Genius MCP Server exposes the Genius.com knowledge base to any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, etc.). It lets the AI:

• Search for songs and artists by name
• Fetch full song metadata — title, album, release date, lyrics state, and Genius editorial descriptions
• Fetch artist profiles — bio, follower count, verification status
• Browse an artist's discography — sorted by popularity or release date, or as a full album list with tracklists
• Read annotations — community and artist-verified explanations of specific lyric fragments, each tagged with a trust level so the AI knows how much weight to give them
• Read album artwork annotations — community explanations of visual elements, symbolism, and artistic choices written directly on album cover art images
• Explore song relationships — discover what a song samples, interpolates, covers, or remixes, and what later songs sampled it in turn
• Look up song credits — writers, producers, featured artists, and custom performance roles (mixing engineer, recording studio, label)
• Run pre-built analysis prompts that gather all relevant data in one shot and ask the AI for a deep analysis of a song or artist

Tools

Some tools call the official Genius API (`api.genius.com`) using your access token. Others use the `lyricsgenius` Python library, which accesses Genius's undocumented public API — these endpoints are not part of the official API contract and may change without notice.

Prompts

Prompts are pre-built multi-step workflows that gather data from Genius and feed it to the AI in a structured context.

`analyze-song`

Args: `song_title` (required), `artist_name` (optional)

Searches for the song, fetches its full metadata and editorial description, retrieves all annotations (sorted by trust level), and asks the AI for a deep analysis of the song's meaning, themes, and cultural context.

`artist-deep-dive`

Args: `artist_name` (required)

Fetches the artist's full bio, their top 3 most popular songs with metadata and artist-verified annotations (where available), and asks the AI for an overview of the artist's themes, style, and significance.

Getting Started

1. Get a Genius API Token

1. Go to https://genius.com/api-clients and sign in.

2. Create a new API client.

3. Copy the Client Access Token — this is the value you'll use for `GENIUS_ACCESS_TOKEN`.

2. Configure Environment Variables

Copy the example env file and fill in your token:

cp .env.example .env

Edit `.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. Run with Python

Requirements: Python 3.11+

Install dependencies:

pip install -r requirements.txt

Run the server:

python main.py

The server will start on `http://127.0.0.1:8080` (Streamable HTTP mode) or in stdio mode depending on your `STREAMABLE_HTTP` setting.

4. Run with Docker

Streamable HTTP mode (default):

docker compose up --build

The server runs as `genius-mcp-server` on port 8080. The `.env` file is mounted into the container — make sure it exists and contains your token before starting.

stdio mode (e.g. for Claude Desktop via Docker):

Set `STREAMABLE_HTTP=false` in your `.env`, then run:

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

Transport Modes

Connecting to an MCP Client

Claude Code (Streamable HTTP)

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

Claude Desktop (stdio)

With `STREAMABLE_HTTP=false` in your `.env`, add this to your `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"
      }
    }
  }
}

Annotation Trust Levels

Every annotation returned by the server includes a `trust_level` field. This lets the AI reason about source reliability:

The `get_song_annotations` tool accepts a `filter` argument to retrieve only annotations at a specific trust level.

Project Structure

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

License

MIT