Content
# 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:**
```bash
git clone <repository-url>
cd MusicBrainzMcp
```
2. **Create virtual environment:**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install dependencies:**
```bash
pip install -e .
```
4. **Run the server:**
```bash
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](https://smithery.ai):
1. **Visit [smithery.ai](https://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
- **[API Reference](docs/api_reference.md)** - Complete documentation of all 10 MCP tools
- **[Configuration Guide](docs/configuration.md)** - Environment variables and configuration options
- **[Usage Examples](docs/examples.md)** - Practical examples and tutorials
- **[Client Testing Guide](docs/CLIENT_TESTING.md)** - FastMCP client implementation and testing
- **[Test Results](docs/TEST_RESULTS.md)** - Comprehensive test results (100% success rate)
- **[Deployment Guide](#deployment)** - Production deployment instructions
## 🛠️ Available MCP Tools
| Tool | Description | Example Use Case |
|------|-------------|------------------|
| `search_artist` | Search for artists by name | Find "The Beatles" |
| `search_release` | Search for releases/albums | Find "Abbey Road" album |
| `search_recording` | Search for individual tracks | Find "Come Together" song |
| `search_release_group` | Search for release groups | Find album groups |
| `get_artist_details` | Get detailed artist info by MBID | Get Beatles discography |
| `get_release_details` | Get detailed release info | Get album track listing |
| `get_recording_details` | Get detailed recording info | Get song metadata |
| `browse_artist_releases` | Browse an artist's releases | List Beatles albums |
| `browse_artist_recordings` | Browse an artist's recordings | List Beatles songs |
| `lookup_by_mbid` | Generic lookup by MusicBrainz ID | Get any entity by ID |
## ⚙️ Configuration
### Environment Variables
```bash
# 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:
```json
{
"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
```python
# Using MCP client to search for artists
result = await client.call_tool("search_artist", {
"params": {
"query": "The Beatles",
"limit": 10
}
})
```
### Get Artist Details
```python
# 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
```python
# 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 [docs/examples.md](docs/examples.md).
## 🚀 Deployment
### Docker Deployment
1. **Build the Docker image:**
```bash
docker build -t musicbrainz-mcp .
```
2. **Run the container:**
```bash
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`:
```ini
[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:
```bash
# 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:**
```bash
git clone <repository-url>
cd MusicBrainzMcp
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
```
2. **Install pre-commit hooks:**
```bash
pre-commit install
```
3. **Run tests:**
```bash
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:
```bash
export DEBUG=true
python -m musicbrainz_mcp.main
```
### Health Check
Test server connectivity:
```python
# 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 [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **[MusicBrainz](https://musicbrainz.org/)** - For providing the comprehensive music database
- **[FastMCP](https://github.com/jlowin/fastmcp)** - For the excellent MCP framework
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - For the standardized protocol
## 📞 Support
- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-repo/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
```bash
# 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
```bash
# 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:**
```json
{
"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
```bash
# 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 [LICENSE](LICENSE) file for details.
## Acknowledgments
- [MusicBrainz](https://musicbrainz.org/) for providing the comprehensive music database
- [FastMCP](https://github.com/jlowin/fastmcp) for the excellent MCP framework
- [Model Context Protocol](https://modelcontextprotocol.io/) for the standardized protocol
## Support
- 📖 [Documentation](docs/)
- 🐛 [Issue Tracker](https://github.com/yourusername/musicbrainz-mcp/issues)
- 💬 [Discussions](https://github.com/yourusername/musicbrainz-mcp/discussions)
---
Made with ❤️ for the music community
[](https://smithery.ai/server/@usercourses63/musicbrainz-mcp-server)
