Hooktheory

You run a Model Context Protocol (MCP) server that lets AI agents interact with Hooktheory for chord progressions, song analysis, and music theory data. This guide shows you how to install, run, and use the server with an MCP client, so your AI can access music theory data on demand.

How to use

You connect an MCP client to the Hooktheory MCP server to request chord progressions, analyze songs, and explore popular or similar progressions. Start the server locally, then configure your MCP client to talk to it. Once connected, you can ask your AI to search for songs by progression, analyze specific tracks, discover common progressions, or find songs with similar chord patterns.

How to install

Prerequisites: Python 3.11 or higher and a Hooktheory account.

# Install and run the MCP server (recommended)
uvx hooktheory-mcp

Or install from source and sync the project, then run locally.

git clone <repository-url>
cd hooktheory-mcp
uv sync

Set up authentication by providing your Hooktheory credentials.

export HOOKTHEORY_USERNAME="your-username"
export HOOKTHEORY_PASSWORD="your-password"

Or place credentials in a .env file.

HOOKTHEORY_USERNAME=your-username
HOOKTHEORY_PASSWORD=your-password

Test the installation to confirm the MCP server is ready.

uvx hooktheory-mcp --help
# Or if installed from source:
uv run hooktheory-mcp --help

Configuration for MCP clients

Configure your MCP client to start and connect the Hooktheory MCP server. Use the following JSON configuration as a starting point.

{
  "mcpServers": {
    "hooktheory": {
      "command": "uvx",
      "args": ["hooktheory-mcp"],
      "env": {
        "HOOKTHEORY_USERNAME": "your-username",
        "HOOKTHEORY_PASSWORD": "your-password"
      }
    }
  }
}

Alternative development/local setup

If you prefer running from a local checkout without using the global package, use the local development command.

{
  "mcpServers": {
    "hooktheory": {
      "command": "uv",
      "args": ["run", "hooktheory-mcp"],
      "cwd": "/path/to/hooktheory-mcp",
      "env": {
        "HOOKTHEORY_USERNAME": "your-username",
        "HOOKTHEORY_PASSWORD": "your-password"
      }
    }
  }
}

Troubleshooting and tips

Common issues you may encounter and how to fix them.

Authentication credentials are required for the Hooktheory API. Ensure both HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD are set.

If you see an HTTP 401 Unauthorized error, verify your credentials. The server will retry authentication automatically.

Rate limits may trigger automatic backoff. The server handles exponential backoff on 429 responses.

For connection issues, check your internet connection and the Hooktheory API status.

Debug mode can help diagnose issues by enabling verbose logging.

export PYTHONPATH=src
python -c "import logging; logging.basicConfig(level=logging.DEBUG); from hooktheory_mcp import main; main()"

Available tools

get_chord_progressions

Search for songs that contain a specific chord progression, with optional filters for key, mode, artist, and song.

analyze_song

Analyze a given song to retrieve its chord progression and underlying music theory data.

get_popular_progressions

Return the most common chord progressions, with optional key, mode, and limit parameters.

find_similar_songs

Find songs that share similar chord progressions to a reference track, with a similarity threshold.

generate_progression

Create new chord progressions based on theory patterns, with options for key, mode, length, and style.