Hooktheory MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with the Hooktheory API for chord progression generation, song analysis, and music theory data retrieval.

Quick Start

Get up and running in 3 simple steps:

1. Set up authentication using your Hooktheory account credentials:

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

2. Install and run:

   uvx hooktheory-mcp

3. Try these examples with your AI assistant:

   • "Find songs with the chord progression I-V-vi-IV"

   • "Analyze the song 'Wonderwall' by Oasis"

   • "Show me popular chord progressions in C major"

   • "Find songs similar to 'Let It Be' by The Beatles"

That's it! Your AI can now access music theory data and chord progressions.

Common Usage Examples

Search for Songs by Chord Progression

Analyze Any Song

Discover Popular Progressions

Find Similar Songs

Features

The server provides the following tools for music analysis and generation:

• Chord Progression Search: Find songs with specific chord progressions

• Song Analysis: Analyze specific songs to get chord progressions and key information

• Popular Progressions: Discover the most popular chord progressions

• Similar Songs: Find songs with similar chord progressions

• Progression Generation: Generate chord progressions based on music theory patterns

Installation

Prerequisites

• Python 3.11 or higher

• A Hooktheory account (Sign up at https://www.hooktheory.com)

Setup

1. Install with uvx (recommended):

   uvx hooktheory-mcp

2. Or install from source:

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

3. Set up authentication:

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

   Or create a .env file:

   HOOKTHEORY_USERNAME=your-username HOOKTHEORY_PASSWORD=your-password

4. Test the installation:

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

Usage

Command Line

The server can be run in different modes:

Standard MCP mode (stdio transport):

Streamable HTTP mode for web integration:

Server-Sent Events (SSE) mode:

MCP Client Configuration

For Claude Desktop, add this to your configuration:

Alternative for development/local install:

Available Tools

1. get_chord_progressions

Search for songs with specific chord progressions.

Parameters:

• cp (required): Chord progression in Roman numeral notation (e.g., "1,5,6,4")

• key (optional): Musical key (e.g., "C", "Am")

• mode (optional): Scale mode ("major", "minor")

• artist (optional): Filter by artist name

• song (optional): Filter by song title

Example:

2. analyze_song

Analyze a specific song to get its chord progression and music theory data.

Parameters:

• artist (required): Artist name

• song (required): Song title

Example:

3. get_popular_progressions

Get the most popular chord progressions from the database.

Parameters:

• key (optional): Filter by musical key

• mode (optional): Filter by scale mode

• limit (optional): Max results (default: 20)

Example:

4. find_similar_songs

Find songs with similar chord progressions to a reference song.

Parameters:

• artist (required): Reference artist name

• song (required): Reference song title

• similarity_threshold (optional): Similarity score 0.0-1.0 (default: 0.7)

Example:

5. generate_progression

Generate chord progressions based on music theory patterns.

Parameters:

• key (optional): Starting key (default: "C")

• mode (optional): Scale mode (default: "major")

• length (optional): Number of chords (default: 4)

• style (optional): Musical style hint ("pop", "rock", "jazz")

Example:

API Integration

The server integrates with the Hooktheory API using OAuth 2.0 authentication:

• Base URL: https://www.hooktheory.com/api

• Authentication: OAuth 2.0 with username/password → Bearer token

• Rate Limiting: 1.5 requests/second with exponential backoff

• Token Management: Automatic token caching and refresh (24-hour expiry)

• Error Recovery: Automatic retry with backoff on rate limits and auth failures

Authentication Flow

1. Server exchanges username/password for Bearer token via POST /users/auth

2. Token is cached and automatically refreshed when expired

3. All API requests use Bearer token authentication

4. Rate limiting prevents exceeding API limits with intelligent backoff

Development

Project Structure

Adding New Tools

To add new tools, edit src/hooktheory_mcp/__init__.py and add new functions decorated with @mcp.tool():

Testing

Troubleshooting

Common Issues

1. Authentication Credentials Not Set

   Error: HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD environment variables are required

   Solution: Set both HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD environment variables

2. HTTP 401 Unauthorized

   HTTP error calling https://www.hooktheory.com/api/trends/...: 401

   Solution: Verify your username and password are correct. The server will automatically retry authentication.

3. Rate Limited (HTTP 429)

   Rate limited. Waiting X seconds before retry

   Solution: This is normal - the server automatically handles rate limiting with exponential backoff

4. Connection Errors

   HTTP error calling https://www.hooktheory.com/api/trends/...: ConnectError

   Solution: Check internet connection and Hooktheory API status

Debug Mode

Enable debug logging:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Hooktheory API Documentation

• Model Context Protocol Specification

• MCP Python SDK