{"id":"5fc467b7-80f1-460c-b916-0b30f1180208","slug":"usercourses63-musicbrainz-mcp-server","kind":"mcp","name":"musicbrainz-mcp-server","summary":"🎵 A comprehensive Model Context Protocol (MCP) server for querying the MusicBrainz database. Built with FastMCP framework, featuring 10 MCP tools, async architecture, comprehensive testing, and produ","owner":"usercourses63","repoUrl":"https://github.com/usercourses63/musicbrainz-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-09-04T06:15:55.000Z","addedAt":"2026-10-21T15:49:14.231Z","logoUrl":"https://avatars.githubusercontent.com/u/153175511?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","databases","developer-tools"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T20:38:02.558Z","sample":false,"url":"https://conduits.dev/tools/usercourses63-musicbrainz-mcp-server","language":"Python","transports":["stdio"],"install":{"pypi":"musicbrainz-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MusicBrainz MCP Server\n\nA 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.\n\n## 🎵 Features\n\n- **10 Comprehensive MCP Tools** for music database queries\n- **Real-time MusicBrainz API Integration** with rate limiting and error handling\n- **Async/Await Support** for high-performance operations\n- **Comprehensive Caching System** with configurable TTL\n- **Robust Error Handling** with detailed error messages\n- **Flexible Configuration** via environment variables or config files\n- **Production Ready** with comprehensive testing (101 tests, 99% passing)\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.8+\n- Internet connection for MusicBrainz API access\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone <repository-url>\ncd MusicBrainzMcp\n```\n\n2. **Create virtual environment:**\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. **Install dependencies:**\n```bash\npip install -e .\n```\n\n4. **Run the server:**\n```bash\npython -m musicbrainz_mcp.main\n```\n\nThe server will start and be available for MCP client connections.\n\n## 🚀 Quick Start with Smithery.ai\n\nThe easiest way to use the MusicBrainz MCP Server is through [smithery.ai](https://smithery.ai):\n\n1. **Visit [smithery.ai](https://smithery.ai)** and sign in\n2. **Search for \"MusicBrainz MCP Server\"** in the tool directory\n3. **Configure your settings:**\n   - User Agent: `YourApp/1.0.0 (your.email@example.com)`\n   - Rate Limit: `1.0` (requests per second)\n   - Timeout: `30.0` (seconds)\n4. **Start querying music data instantly!**\n\n### Popular Music Queries You Can Try\n\n- Search for **Taylor Swift**: `search_artist` with query \"Taylor Swift\"\n- Find **\"Blinding Lights\"**: `search_recording` with query \"Blinding Lights\"\n- Browse **recent releases**: `browse_artist_releases` for any artist\n- Get **detailed info**: `get_artist_details` with any artist MBID\n\n## 📖 Documentation\n\n- **[API Reference](docs/api_reference.md)** - Complete documentation of all 10 MCP tools\n- **[Configuration Guide](docs/configuration.md)** - Environment variables and configuration options\n- **[Usage Examples](docs/examples.md)** - Practical examples and tutorials\n- **[Client Testing Guide](docs/CLIENT_TESTING.md)** - FastMCP client implementation and testing\n- **[Test Results](docs/TEST_RESULTS.md)** - Comprehensive test results (100% success rate)\n- **[Deployment Guide](#deployment)** - Production deployment instructions\n\n## 🛠️ Available MCP Tools\n\n| Tool | Description | Example Use Case |\n|------|-------------|------------------|\n| `search_artist` | Search for artists by name | Find \"The Beatles\" |\n| `search_release` | Search for releases/albums | Find \"Abbey Road\" album |\n| `search_recording` | Search for individual tracks | Find \"Come Together\" song |\n| `search_release_group` | Search for release groups | Find album groups |\n| `get_artist_details` | Get detailed artist info by MBID | Get Beatles discography |\n| `get_release_details` | Get detailed release info | Get album track listing |\n| `get_recording_details` | Get detailed recording info | Get song metadata |\n| `browse_artist_releases` | Browse an artist's releases | List Beatles albums |\n| `browse_artist_recordings` | Browse an artist's recordings | List Beatles songs |\n| `lookup_by_mbid` | Generic lookup by MusicBrainz ID | Get any entity by ID |\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n```bash\n# MusicBrainz API Configuration\nMUSICBRAINZ_USER_AGENT=\"YourApp/1.0.0\"  # Required: Your app identifier\nMUSICBRAINZ_RATE_LIMIT=\"1.0\"            # Requests per second (default: 1.0)\nMUSICBRAINZ_TIMEOUT=\"10.0\"              # Request timeout in seconds\n\n# Caching Configuration\nCACHE_ENABLED=\"true\"                     # Enable/disable caching\nCACHE_DEFAULT_TTL=\"300\"                  # Cache TTL in seconds (5 minutes)\n\n# Server Configuration\nDEBUG=\"false\"                            # Enable debug logging\n```\n\n### Configuration File\n\nCreate `config.json` in the project root:\n\n```json\n{\n  \"api\": {\n    \"user_agent\": \"YourApp/1.0.0\",\n    \"rate_limit\": 1.0,\n    \"timeout\": 10.0\n  },\n  \"cache\": {\n    \"enabled\": true,\n    \"default_ttl\": 300\n  },\n  \"debug\": false\n}\n```\n\n## 💡 Usage Examples\n\n### Basic Artist Search\n\n```python\n# Using MCP client to search for artists\nresult = await client.call_tool(\"search_artist\", {\n    \"params\": {\n        \"query\": \"The Beatles\",\n        \"limit\": 10\n    }\n})\n```\n\n### Get Artist Details\n\n```python\n# Get detailed information about an artist\nresult = await client.call_tool(\"get_artist_details\", {\n    \"params\": {\n        \"mbid\": \"b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d\",\n        \"inc\": [\"releases\", \"recordings\"]\n    }\n})\n```\n\n### Browse Artist Releases\n\n```python\n# Browse all releases by an artist\nresult = await client.call_tool(\"browse_artist_releases\", {\n    \"params\": {\n        \"artist_mbid\": \"b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d\",\n        \"limit\": 20,\n        \"release_type\": [\"album\"],\n        \"release_status\": [\"official\"]\n    }\n})\n```\n\nFor more examples, see [docs/examples.md](docs/examples.md).\n\n## 🚀 Deployment\n\n### Docker Deployment\n\n1. **Build the Docker image:**\n```bash\ndocker build -t musicbrainz-mcp .\n```\n\n2. **Run the container:**\n```bash\ndocker run -d \\\n  --name musicbrainz-mcp \\\n  -e MUSICBRAINZ_USER_AGENT=\"YourApp/1.0.0\" \\\n  -p 8000:8000 \\\n  musicbrainz-mcp\n```\n\n### Systemd Service\n\nCreate `/etc/systemd/system/musicbrainz-mcp.service`:\n\n```ini\n[Unit]\nDescription=MusicBrainz MCP Server\nAfter=network.target\n\n[Service]\nType=simple\nUser=musicbrainz\nWorkingDirectory=/opt/musicbrainz-mcp\nEnvironment=MUSICBRAINZ_USER_AGENT=YourApp/1.0.0\nExecStart=/opt/musicbrainz-mcp/venv/bin/python -m musicbrainz_mcp.main\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\n### Cloud Deployment\n\nThe server can be deployed on any cloud platform that supports Python applications:\n- **Heroku**: Use the included `Procfile`\n- **AWS Lambda**: Package as a serverless function\n- **Google Cloud Run**: Use the Docker container\n- **Azure Container Instances**: Deploy the Docker image\n\n## 🧪 Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=musicbrainz_mcp\n\n# Run only unit tests\npytest -m unit\n\n# Run only integration tests\npytest -m integration\n\n# Run with verbose output\npytest -v\n```\n\n**Test Results:**\n- ✅ **101 total tests**\n- ✅ **100 passing, 1 skipped**\n- ✅ **99% success rate**\n- ✅ **Zero failures, zero warnings**\n\n## 🛠️ Development\n\n### Setup Development Environment\n\n1. **Clone and setup:**\n```bash\ngit clone <repository-url>\ncd MusicBrainzMcp\npython -m venv venv\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n2. **Install pre-commit hooks:**\n```bash\npre-commit install\n```\n\n3. **Run tests:**\n```bash\npytest\n```\n\n### Project Structure\n\n```\nMusicBrainzMcp/\n├── src/musicbrainz_mcp/          # Main package\n│   ├── __init__.py\n│   ├── main.py                   # Server entry point\n│   ├── server.py                 # FastMCP server implementation\n│   ├── musicbrainz_client.py     # MusicBrainz API client\n│   ├── models.py                 # Pydantic data models\n│   ├── schemas.py                # Response schemas\n│   ├── config.py                 # Configuration management\n│   ├── cache.py                  # Caching system\n│   ├── exceptions.py             # Custom exceptions\n│   └── utils.py                  # Utility functions\n├── tests/                        # Test suite\n│   ├── test_client.py           # Client tests\n│   ├── test_server.py           # Server tests\n│   ├── test_models.py           # Model tests\n│   ├── test_utils.py            # Utility tests\n│   ├── test_integration.py      # Integration tests\n│   └── mock_data.py             # Test data\n├── docs/                        # Documentation\n├── examples/                    # Usage examples\n└── pyproject.toml              # Project configuration\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**1. Rate Limit Errors**\n```\nMusicBrainzRateLimitError: Rate limit exceeded\n```\n- **Solution**: Reduce the `MUSICBRAINZ_RATE_LIMIT` value or wait before retrying\n- **Default**: 1 request per second (MusicBrainz recommendation)\n\n**2. Network Timeout**\n```\nMusicBrainzAPIError: Request timeout\n```\n- **Solution**: Increase `MUSICBRAINZ_TIMEOUT` value or check network connectivity\n- **Default**: 10 seconds\n\n**3. Invalid MBID Format**\n```\nValidationError: Invalid MBID format\n```\n- **Solution**: Ensure MBIDs are valid UUID format (e.g., `b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d`)\n\n**4. Missing User Agent**\n```\nMusicBrainzAPIError: User agent required\n```\n- **Solution**: Set `MUSICBRAINZ_USER_AGENT` environment variable\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\nexport DEBUG=true\npython -m musicbrainz_mcp.main\n```\n\n### Health Check\n\nTest server connectivity:\n\n```python\n# Test basic connectivity\nresult = await client.call_tool(\"search_artist\", {\n    \"params\": {\"query\": \"test\", \"limit\": 1}\n})\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** with proper tests\n4. **Run the test suite**: `pytest`\n5. **Commit your changes**: `git commit -m 'Add amazing feature'`\n6. **Push to the branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Development Guidelines\n\n- **Code Style**: Follow PEP 8 and use type hints\n- **Testing**: Add tests for new functionality\n- **Documentation**: Update docs for API changes\n- **Commit Messages**: Use conventional commit format\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **[MusicBrainz](https://musicbrainz.org/)** - For providing the comprehensive music database\n- **[FastMCP](https://github.com/jlowin/fastmcp)** - For the excellent MCP framework\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** - For the standardized protocol\n\n## 📞 Support\n\n- **Documentation**: [docs/](docs/)\n- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/your-repo/discussions)\n\n---\n\n**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.\n\n## Features\n\n- 🎵 **Comprehensive Music Data**: Access artists, albums, recordings, releases, and more\n- 🚀 **FastMCP Framework**: Built on the robust FastMCP framework for reliable MCP protocol handling\n- 🔍 **Powerful Search**: Search across all MusicBrainz entity types with flexible query options\n- 📊 **Rich Metadata**: Get detailed information including relationships, tags, and ratings\n- ⚡ **Async Performance**: Non-blocking async operations for optimal performance\n- 🛡️ **Rate Limiting**: Built-in compliance with MusicBrainz API guidelines\n- 🧪 **Well Tested**: Comprehensive test suite with high code coverage\n- 📚 **Great Documentation**: Detailed docs with examples and API reference\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/musicbrainz-mcp.git\ncd musicbrainz-mcp\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -e \".[dev]\"\n```\n\n### Running the Server\n\n```bash\n# Start the MCP server\nmusicbrainz-mcp\n\n# Or run directly with Python\npython -m musicbrainz_mcp.server\n```\n\n### Basic Usage\n\nThe server provides several MCP tools for querying MusicBrainz:\n\n- `search_artist` - Search for artists by name\n- `search_release` - Search for releases/albums\n- `search_recording` - Search for recordings/tracks\n- `get_artist_details` - Get detailed artist information\n- `get_release_details` - Get detailed release information\n- `lookup_by_mbid` - Direct lookup using MusicBrainz IDs\n\n## MCP Tools\n\n### search_artist\n\nSearch for artists by name or query string.\n\n**Parameters:**\n- `query` (string): Search query for artist name\n- `limit` (integer, optional): Maximum number of results (default: 25)\n- `offset` (integer, optional): Offset for pagination (default: 0)\n\n**Example:**\n```json\n{\n  \"query\": \"The Beatles\",\n  \"limit\": 10\n}\n```\n\n### search_release\n\nSearch for releases (albums, singles, etc.) by title or artist.\n\n**Parameters:**\n- `query` (string): Search query for release title\n- `artist` (string, optional): Filter by artist name\n- `limit` (integer, optional): Maximum number of results (default: 25)\n- `offset` (integer, optional): Offset for pagination (default: 0)\n\n### search_recording\n\nSearch for recordings (individual tracks) by title or artist.\n\n**Parameters:**\n- `query` (string): Search query for recording title\n- `artist` (string, optional): Filter by artist name\n- `limit` (integer, optional): Maximum number of results (default: 25)\n- `offset` (integer, optional): Offset for pagination (default: 0)\n\n### get_artist_details\n\nGet detailed information about a specific artist.\n\n**Parameters:**\n- `mbid` (string): MusicBrainz ID of the artist\n- `include` (array, optional): Additional data to include (releases, recordings, etc.)\n\n### get_release_details\n\nGet detailed information about a specific release.\n\n**Parameters:**\n- `mbid` (string): MusicBrainz ID of the release\n- `include` (array, optional): Additional data to include (tracks, artist-credits, etc.)\n\n### lookup_by_mbid\n\nDirect lookup of any entity by its MusicBrainz ID.\n\n**Parameters:**\n- `mbid` (string): MusicBrainz ID\n- `entity_type` (string): Type of entity (artist, release, recording, etc.)\n- `include` (array, optional): Additional data to include\n\n## Configuration\n\nThe server can be configured through environment variables:\n\n- `MUSICBRAINZ_USER_AGENT`: Custom User-Agent for API requests\n- `MUSICBRAINZ_RATE_LIMIT`: Rate limit in requests per second (default: 1.0)\n- `MUSICBRAINZ_TIMEOUT`: Request timeout in seconds (default: 30)\n- `MUSICBRAINZ_BASE_URL`: Base URL for MusicBrainz API (default: https://musicbrainz.org/ws/2)\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=musicbrainz_mcp --cov-report=html\n\n# Format code\nblack src tests\nruff check src tests\n\n# Type checking\nmypy src\n```\n\n### Project Structure\n\n```\nmusicbrainz-mcp/\n├── src/musicbrainz_mcp/\n│   ├── __init__.py          # Package initialization\n│   ├── server.py            # Main MCP server implementation\n│   ├── musicbrainz_client.py # MusicBrainz API client\n│   ├── models.py            # Pydantic data models\n│   ├── tools.py             # MCP tool definitions\n│   ├── utils.py             # Utility functions\n│   ├── config.py            # Configuration management\n│   └── exceptions.py        # Custom exceptions\n├── tests/                   # Test suite\n├── docs/                    # Documentation\n├── examples/                # Usage examples\n└── pyproject.toml          # Project configuration\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for your changes\n5. Run the test suite (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [MusicBrainz](https://musicbrainz.org/) for providing the comprehensive music database\n- [FastMCP](https://github.com/jlowin/fastmcp) for the excellent MCP framework\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the standardized protocol\n\n## Support\n\n- 📖 [Documentation](docs/)\n- 🐛 [Issue Tracker](https://github.com/yourusername/musicbrainz-mcp/issues)\n- 💬 [Discussions](https://github.com/yourusername/musicbrainz-mcp/discussions)\n\n---\n\nMade with ❤️ for the music community\n[![smithery badge](https://smithery.ai/badge/@usercourses63/musicbrainz-mcp-server)](https://smithery.ai/server/@usercourses63/musicbrainz-mcp-server)\n"}