usercourses63/musicbrainz-mcp-server

MusicBrainz MCP Server

A comprehensive Model Context Protocol (MCP) server for querying the MusicBrainz database, built with FastMCP framework. This server provides seamless access to music metadata including artists, releases, recordings, and more through a standardized MCP interface.

🎵 Features

• 10 Comprehensive MCP Tools for music database queries
• Real-time MusicBrainz API Integration with rate limiting and error handling
• Async/Await Support for high-performance operations
• Comprehensive Caching System with configurable TTL
• Robust Error Handling with detailed error messages
• Flexible Configuration via environment variables or config files
• Production Ready with comprehensive testing (101 tests, 99% passing)

🚀 Quick Start

Prerequisites

• Python 3.8+
• Internet connection for MusicBrainz API access

Installation

1. Clone the repository:

git clone <repository-url>
cd MusicBrainzMcp

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -e .

4. Run the server:

python -m musicbrainz_mcp.main

The server will start and be available for MCP client connections.

🚀 Quick Start with Smithery.ai

The easiest way to use the MusicBrainz MCP Server is through smithery.ai:

1. Visit smithery.ai and sign in
2. Search for "MusicBrainz MCP Server" in the tool directory
3. Configure your settings:
   • User Agent: YourApp/1.0.0 (your.email@example.com)
   • Rate Limit: 1.0 (requests per second)
   • Timeout: 30.0 (seconds)
4. Start querying music data instantly!

Popular Music Queries You Can Try

• Search for Taylor Swift: search_artist with query "Taylor Swift"
• Find "Blinding Lights": search_recording with query "Blinding Lights"
• Browse recent releases: browse_artist_releases for any artist
• Get detailed info: get_artist_details with any artist MBID

📖 Documentation

• - Complete documentation of all 10 MCP tools
• - Environment variables and configuration options
• - Practical examples and tutorials
• - FastMCP client implementation and testing
• - Comprehensive test results (100% success rate)
• Deployment Guide - Production deployment instructions

🛠️ Available MCP Tools

⚙️ Configuration

Environment Variables

# MusicBrainz API Configuration
MUSICBRAINZ_USER_AGENT="YourApp/1.0.0"  # Required: Your app identifier
MUSICBRAINZ_RATE_LIMIT="1.0"            # Requests per second (default: 1.0)
MUSICBRAINZ_TIMEOUT="10.0"              # Request timeout in seconds

# Caching Configuration
CACHE_ENABLED="true"                     # Enable/disable caching
CACHE_DEFAULT_TTL="300"                  # Cache TTL in seconds (5 minutes)

# Server Configuration
DEBUG="false"                            # Enable debug logging

Configuration File

Create config.json in the project root:

{
  "api": {
    "user_agent": "YourApp/1.0.0",
    "rate_limit": 1.0,
    "timeout": 10.0
  },
  "cache": {
    "enabled": true,
    "default_ttl": 300
  },
  "debug": false
}

💡 Usage Examples

Basic Artist Search

# Using MCP client to search for artists
result = await client.call_tool("search_artist", {
    "params": {
        "query": "The Beatles",
        "limit": 10
    }
})

Get Artist Details

# Get detailed information about an artist
result = await client.call_tool("get_artist_details", {
    "params": {
        "mbid": "b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d",
        "inc": ["releases", "recordings"]
    }
})

Browse Artist Releases

# Browse all releases by an artist
result = await client.call_tool("browse_artist_releases", {
    "params": {
        "artist_mbid": "b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d",
        "limit": 20,
        "release_type": ["album"],
        "release_status": ["official"]
    }
})

For more examples, see .

🚀 Deployment

Docker Deployment

1. Build the Docker image:

docker build -t musicbrainz-mcp .

2. Run the container:

docker run -d \
  --name musicbrainz-mcp \
  -e MUSICBRAINZ_USER_AGENT="YourApp/1.0.0" \
  -p 8000:8000 \
  musicbrainz-mcp

Systemd Service

Create /etc/systemd/system/musicbrainz-mcp.service:

[Unit]
Description=MusicBrainz MCP Server
After=network.target

[Service]
Type=simple
User=musicbrainz
WorkingDirectory=/opt/musicbrainz-mcp
Environment=MUSICBRAINZ_USER_AGENT=YourApp/1.0.0
ExecStart=/opt/musicbrainz-mcp/venv/bin/python -m musicbrainz_mcp.main
Restart=always

[Install]
WantedBy=multi-user.target

Cloud Deployment

The server can be deployed on any cloud platform that supports Python applications:

• Heroku: Use the included Procfile
• AWS Lambda: Package as a serverless function
• Google Cloud Run: Use the Docker container
• Azure Container Instances: Deploy the Docker image

🧪 Testing

Run the comprehensive test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=musicbrainz_mcp

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

# Run with verbose output
pytest -v

Test Results:

• ✅ 101 total tests
• ✅ 100 passing, 1 skipped
• ✅ 99% success rate
• ✅ Zero failures, zero warnings

🛠️ Development

Setup Development Environment

1. Clone and setup:

git clone <repository-url>
cd MusicBrainzMcp
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

2. Install pre-commit hooks:

pre-commit install

3. Run tests:

pytest

Project Structure

MusicBrainzMcp/
├── src/musicbrainz_mcp/          # Main package
│   ├── __init__.py
│   ├── main.py                   # Server entry point
│   ├── server.py                 # FastMCP server implementation
│   ├── musicbrainz_client.py     # MusicBrainz API client
│   ├── models.py                 # Pydantic data models
│   ├── schemas.py                # Response schemas
│   ├── config.py                 # Configuration management
│   ├── cache.py                  # Caching system
│   ├── exceptions.py             # Custom exceptions
│   └── utils.py                  # Utility functions
├── tests/                        # Test suite
│   ├── test_client.py           # Client tests
│   ├── test_server.py           # Server tests
│   ├── test_models.py           # Model tests
│   ├── test_utils.py            # Utility tests
│   ├── test_integration.py      # Integration tests
│   └── mock_data.py             # Test data
├── docs/                        # Documentation
├── examples/                    # Usage examples
└── pyproject.toml              # Project configuration

🔧 Troubleshooting

Common Issues

1. Rate Limit Errors

MusicBrainzRateLimitError: Rate limit exceeded

• Solution: Reduce the MUSICBRAINZ_RATE_LIMIT value or wait before retrying
• Default: 1 request per second (MusicBrainz recommendation)

2. Network Timeout

MusicBrainzAPIError: Request timeout

• Solution: Increase MUSICBRAINZ_TIMEOUT value or check network connectivity
• Default: 10 seconds

3. Invalid MBID Format

ValidationError: Invalid MBID format

• Solution: Ensure MBIDs are valid UUID format (e.g., b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d)

4. Missing User Agent

MusicBrainzAPIError: User agent required

• Solution: Set MUSICBRAINZ_USER_AGENT environment variable

Debug Mode

Enable debug logging for troubleshooting:

export DEBUG=true
python -m musicbrainz_mcp.main

Health Check

Test server connectivity:

# Test basic connectivity
result = await client.call_tool("search_artist", {
    "params": {"query": "test", "limit": 1}
})

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with proper tests
4. Run the test suite: pytest
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Code Style: Follow PEP 8 and use type hints
• Testing: Add tests for new functionality
• Documentation: Update docs for API changes
• Commit Messages: Use conventional commit format

📄 License

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

🙏 Acknowledgments

• MusicBrainz - For providing the comprehensive music database
• FastMCP - For the excellent MCP framework
• Model Context Protocol - For the standardized protocol

📞 Support

• Documentation:
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for the music community This server provides comprehensive access to music metadata including artists, albums, recordings, releases, and related information through a standardized MCP interface.

Features

• 🎵 Comprehensive Music Data: Access artists, albums, recordings, releases, and more
• 🚀 FastMCP Framework: Built on the robust FastMCP framework for reliable MCP protocol handling
• 🔍 Powerful Search: Search across all MusicBrainz entity types with flexible query options
• 📊 Rich Metadata: Get detailed information including relationships, tags, and ratings
• ⚡ Async Performance: Non-blocking async operations for optimal performance
• 🛡️ Rate Limiting: Built-in compliance with MusicBrainz API guidelines
• 🧪 Well Tested: Comprehensive test suite with high code coverage
• 📚 Great Documentation: Detailed docs with examples and API reference

Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/musicbrainz-mcp.git
cd musicbrainz-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Running the Server

# Start the MCP server
musicbrainz-mcp

# Or run directly with Python
python -m musicbrainz_mcp.server

Basic Usage

The server provides several MCP tools for querying MusicBrainz:

• search_artist - Search for artists by name
• search_release - Search for releases/albums
• search_recording - Search for recordings/tracks
• get_artist_details - Get detailed artist information
• get_release_details - Get detailed release information
• lookup_by_mbid - Direct lookup using MusicBrainz IDs

MCP Tools

search_artist

Search for artists by name or query string.

Parameters:

• query (string): Search query for artist name
• limit (integer, optional): Maximum number of results (default: 25)
• offset (integer, optional): Offset for pagination (default: 0)

Example:

{
  "query": "The Beatles",
  "limit": 10
}

search_release

Search for releases (albums, singles, etc.) by title or artist.

Parameters:

• query (string): Search query for release title
• artist (string, optional): Filter by artist name
• limit (integer, optional): Maximum number of results (default: 25)
• offset (integer, optional): Offset for pagination (default: 0)

search_recording

Search for recordings (individual tracks) by title or artist.

Parameters:

• query (string): Search query for recording title
• artist (string, optional): Filter by artist name
• limit (integer, optional): Maximum number of results (default: 25)
• offset (integer, optional): Offset for pagination (default: 0)

get_artist_details

Get detailed information about a specific artist.

Parameters:

• mbid (string): MusicBrainz ID of the artist
• include (array, optional): Additional data to include (releases, recordings, etc.)

get_release_details

Get detailed information about a specific release.

Parameters:

• mbid (string): MusicBrainz ID of the release
• include (array, optional): Additional data to include (tracks, artist-credits, etc.)

lookup_by_mbid

Direct lookup of any entity by its MusicBrainz ID.

Parameters:

• mbid (string): MusicBrainz ID
• entity_type (string): Type of entity (artist, release, recording, etc.)
• include (array, optional): Additional data to include

Configuration

The server can be configured through environment variables:

• MUSICBRAINZ_USER_AGENT: Custom User-Agent for API requests
• MUSICBRAINZ_RATE_LIMIT: Rate limit in requests per second (default: 1.0)
• MUSICBRAINZ_TIMEOUT: Request timeout in seconds (default: 30)
• MUSICBRAINZ_BASE_URL: Base URL for MusicBrainz API (default: https://musicbrainz.org/ws/2)

Development

Setup Development Environment

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run tests with coverage
pytest --cov=musicbrainz_mcp --cov-report=html

# Format code
black src tests
ruff check src tests

# Type checking
mypy src

Project Structure

musicbrainz-mcp/
├── src/musicbrainz_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server implementation
│   ├── musicbrainz_client.py # MusicBrainz API client
│   ├── models.py            # Pydantic data models
│   ├── tools.py             # MCP tool definitions
│   ├── utils.py             # Utility functions
│   ├── config.py            # Configuration management
│   └── exceptions.py        # Custom exceptions
├── tests/                   # Test suite
├── docs/                    # Documentation
├── examples/                # Usage examples
└── pyproject.toml          # Project configuration

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

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

Acknowledgments

• MusicBrainz for providing the comprehensive music database
• FastMCP for the excellent MCP framework
• Model Context Protocol for the standardized protocol

Support

• 📖
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the music community