# 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
[![smithery badge](https://smithery.ai/badge/@usercourses63/musicbrainz-mcp-server)](https://smithery.ai/server/@usercourses63/musicbrainz-mcp-server)