Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hooktheory MCP Server find songs with the chord progression I-V-vi-IV in C major"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Get up and running in 3 simple steps:
Set up authentication using your Hooktheory account credentials:
export HOOKTHEORY_USERNAME="your-username"
export HOOKTHEORY_PASSWORD="your-password"Install and run:
uvx hooktheory-mcpTry 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.
Related MCP server: Scribbletune MCP Server
Find songs using the progression 1,5,6,4 in the key of C majorWhat are the chords in "Someone Like You" by Adele?What are the most common chord progressions in pop music?Find songs that have similar chord progressions to "Hotel California"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
Python 3.11 or higher
A Hooktheory account (Sign up at https://www.hooktheory.com)
Install with uvx (recommended):
uvx hooktheory-mcpOr install from source:
git clone <repository-url>
cd hooktheory-mcp
uv syncSet up authentication:
export HOOKTHEORY_USERNAME="your-username"
export HOOKTHEORY_PASSWORD="your-password"Or create a .env file:
HOOKTHEORY_USERNAME=your-username
HOOKTHEORY_PASSWORD=your-passwordTest the installation:
uvx hooktheory-mcp --help
# Or if installed from source:
uv run hooktheory-mcp --helpThe server can be run in different modes:
Standard MCP mode (stdio transport):
uvx hooktheory-mcp
# Or from source: uv run hooktheory-mcpStreamable HTTP mode for web integration:
uvx hooktheory-mcp --transport streamable-http
# Or from source: uv run hooktheory-mcp --transport streamable-httpServer-Sent Events (SSE) mode:
uvx hooktheory-mcp --transport sse
# Or from source: uv run hooktheory-mcp --transport sseFor Claude Desktop, add this to your configuration:
{
"mcpServers": {
"hooktheory": {
"command": "uvx",
"args": ["hooktheory-mcp"],
"env": {
"HOOKTHEORY_USERNAME": "your-username",
"HOOKTHEORY_PASSWORD": "your-password"
}
}
}
}Alternative for development/local install:
{
"mcpServers": {
"hooktheory": {
"command": "uv",
"args": ["run", "hooktheory-mcp"],
"cwd": "/path/to/hooktheory-mcp",
"env": {
"HOOKTHEORY_USERNAME": "your-username",
"HOOKTHEORY_PASSWORD": "your-password"
}
}
}
}get_chord_progressionsSearch 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:
Find songs with the progression I-V-vi-IV in the key of C majoranalyze_songAnalyze a specific song to get its chord progression and music theory data.
Parameters:
artist (required): Artist name
song (required): Song title
Example:
Analyze "Wonderwall" by Oasisget_popular_progressionsGet 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:
Show me the most popular chord progressions in C majorfind_similar_songsFind 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:
Find songs similar to "Let It Be" by The Beatlesgenerate_progressionGenerate 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:
Generate a 4-chord pop progression in A minorThe 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
Server exchanges username/password for Bearer token via POST /users/auth
Token is cached and automatically refreshed when expired
All API requests use Bearer token authentication
Rate limiting prevents exceeding API limits with intelligent backoff
hooktheory-mcp/
├── src/hooktheory_mcp/
│ └── __init__.py # Main MCP server implementation
├── pyproject.toml # Project configuration
├── uv.lock # Dependency lock file
└── README.md # This fileTo add new tools, edit src/hooktheory_mcp/__init__.py and add new functions decorated with @mcp.tool():
@mcp.tool()
async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
"""
Description of your tool.
Args:
param1: Description of parameter
param2: Optional parameter description
Returns:
Description of return value
"""
# Implementation here
return result# Run basic connectivity test
uv run python -c "
import asyncio
from hooktheory_mcp import hooktheory_client
asyncio.run(hooktheory_client._make_request('test'))
"Authentication Credentials Not Set
Error: HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD environment variables are requiredSolution: Set both HOOKTHEORY_USERNAME and HOOKTHEORY_PASSWORD environment variables
HTTP 401 Unauthorized
HTTP error calling https://www.hooktheory.com/api/trends/...: 401Solution: Verify your username and password are correct. The server will automatically retry authentication.
Rate Limited (HTTP 429)
Rate limited. Waiting X seconds before retrySolution: This is normal - the server automatically handles rate limiting with exponential backoff
Connection Errors
HTTP error calling https://www.hooktheory.com/api/trends/...: ConnectErrorSolution: Check internet connection and Hooktheory API status
Enable debug logging:
export PYTHONPATH=src
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from hooktheory_mcp import main
main()
"Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
Get chord statistics and transition probabilities from Hooktheory database.
Args:
cp: Optional chord progression to get transitions from (e.g., "4" for chords after IV, "4,1" for chords after IV-I)
If not provided, returns overall chord frequency statistics
key: Musical key filter (e.g., "C", "Am")
mode: Scale mode filter ("major" or "minor")
Returns:
JSON string containing chord nodes with chord_ID, chord_HTML (Roman numeral), probability, and child_path
- Without cp: Shows overall chord frequencies (I=18.9%, IV=17.2%, etc.)
- With cp: Shows what chords follow the progression (e.g., after IV: I=32.4%, V=28.9%)
| Name | Required | Description | Default |
|---|---|---|---|
| cp | No | ||
| key | No | ||
| mode | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explaining the tool's behavior: it describes what happens with and without the 'cp' parameter, specifies the return format (JSON string with specific fields), and provides concrete examples of output probabilities. However, it doesn't mention rate limits, authentication requirements, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently organized. It starts with the core purpose, then explains parameters with examples, then describes returns with concrete scenarios. Every sentence adds value, and the information is appropriately front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, no annotations, and the presence of an output schema, the description provides excellent contextual completeness. It explains the tool's purpose, parameters, behavior, and return format with concrete examples. The output schema handles return value details, allowing the description to focus on behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial value beyond the schema's 0% coverage. It explains all three parameters: 'cp' (chord progression with examples and default behavior), 'key' (musical key filter), and 'mode' (scale mode filter). It provides concrete examples and clarifies the impact of each parameter on the tool's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get chord statistics and transition probabilities from Hooktheory database.' It specifies both overall statistics and transition analysis, distinguishing it from the sibling tool 'get_songs_by_progression' which likely returns songs rather than statistical data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining when to use the tool with or without the 'cp' parameter. It distinguishes between overall chord frequencies and transition probabilities, but doesn't explicitly mention when to use this tool versus the sibling 'get_songs_by_progression' or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get songs that contain a specific chord progression from Hooktheory.
Args:
cp: Chord progression using comma-separated chord IDs (e.g., "1,5,6,4" for I-V-vi-IV, "4,1" for IV-I)
page: Page number for pagination (default: 1, each page contains ~20 results)
key: Musical key filter (e.g., "C", "Am")
mode: Scale mode filter (e.g., "major", "minor")
Returns:
JSON string containing array of songs with artist, song, section, and URL
| Name | Required | Description | Default |
|---|---|---|---|
| cp | Yes | ||
| page | No | ||
| key | No | ||
| mode | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns paginated results (~20 per page) and a JSON string, which adds useful behavioral context beyond the basic read operation. However, it lacks details on rate limits, error handling, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the purpose, followed by clear sections for arguments and returns. Every sentence adds value without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, 1 required) and the presence of an output schema (which covers return values), the description is largely complete. It explains parameters thoroughly and mentions pagination, though it could benefit from more behavioral context like error cases or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter's purpose with examples (e.g., 'cp' uses chord IDs like '1,5,6,4', 'page' defaults to 1, 'key' and 'mode' as filters), fully compensating for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get songs that contain a specific chord progression') and resource ('from Hooktheory'), distinguishing it from the sibling tool 'get_chord_transitions' which likely focuses on chord transitions rather than songs by progression.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the required 'cp' parameter and optional filters, but does not explicitly state when to use this tool versus the sibling 'get_chord_transitions' or other alternatives, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.3get_chord_transitionsget_songs_by_progressionScored across 2 tools
The two tools have clearly distinct purposes: get_chord_transitions retrieves chord statistics and transition probabilities, while get_songs_by_progression finds songs containing specific chord progressions. There is no overlap in functionality, making it easy for an agent to select the correct tool based on whether it needs analytical data or song references.
Both tool names follow a consistent verb_noun pattern with get_ as the verb prefix and descriptive nouns (chord_transitions, songs_by_progression). The naming is predictable and readable, adhering to snake_case throughout without any deviations or mixed conventions.
With only 2 tools, the server feels under-scoped for a music theory domain, as it lacks essential operations like searching for chords, analyzing melodies, or accessing other Hooktheory features. This minimal set may force agents to work around gaps, limiting the server's utility beyond basic queries.
The tool surface is severely incomplete for a Hooktheory server, missing core functionalities such as chord lookup, melody analysis, or accessing user data. While the existing tools cover chord transitions and song searches, they do not provide a full CRUD/lifecycle or comprehensive coverage of the music theory domain, leading to potential agent failures in broader tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Deterministic music theory for agents: analyze, voice, reharmonize, conduct — computed, not guessed
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
Anonymous public tools for Zachary Roth Music. See the published agent boundary before use.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
