A comprehensive Model Context Protocol (MCP) server that bridges the gap between Large Language Models (LLMs) and your self-hosted media technology stack. This project enables intelligent automation and natural language control of your media services while maintaining traditional programmatic access.
🎯 Key Features
- 🤖 LLM-powered natural language control of media services
- 🔌 Modular architecture for easy service integration
- 🔄 Unified API gateway for traditional access
- 🎮 Web UI for visual control (planned)
- 🔐 Direct API access without LLM middleware
- 🧩 Extensible plugin system for new services
📚 Documentation
🏗️ Project Structure
This monorepo is organized into modular packages, each serving a specific purpose:
- 📦
packages/server: Core MCP server implementation - 🌐
packages/web: Web UI interface (planned) - 💬
packages/chatbot: LLM chat interface (planned) - 🔀
packages/api-gateway: API routing and service coordination (planned)
🔧 Integrated Services
✅ Currently Supported
- Gotify - Notification Management
- Sonarr - TV Show Management
- Prowlarr - Indexer Management
- Overseerr - Request Management
🚧 Planned Integrations
- Radarr - Movie Management
- qBittorrent - Torrent Management
- SABnzbd - Usenet Downloads
- Plex - Media Server
- Tautulli - Server Statistics
- TMDB - Media Database
📖 Service Documentation
🟢 Currently Integrated
📋 Planned Integration
🧪 Development
🛠️ SDK References
🏛️ Architecture
The project follows a modular architecture where each service package contains:
- 🔌 API client implementation
- 📝 Type definitions
- 🛠️ MCP tools for service interaction
- 🛣️ API routes
This architecture supports multiple interaction methods:
- LLM-Powered Control: Natural language processing for intuitive media management
- Traditional API Access: Direct API calls through the unified gateway
- Web Interface: Visual control panel for service management (planned)
- Chatbot Interface: Conversational UI for service control (planned)
The modular design allows for:
- Easy addition of new services
- Independent service deployment
- Flexible interaction methods
- Consistent API patterns across services
🚀 Getting Started
Prerequisites
# Clone and setup repository
git clone https://github.com/jmagar/yarr
cd yarr
pnpm install
Configuration
- Create
.env file from template:
Then add your service API keys:
# Sonarr Configuration
SONARR_URL=http://localhost:8989
SONARR_API_KEY=your_sonarr_api_key
# Prowlarr Configuration
PROWLARR_URL=http://localhost:9696
PROWLARR_API_KEY=your_prowlarr_api_key
# Overseerr Configuration
OVERSEERR_URL=http://localhost:5055
OVERSEERR_API_KEY=your_overseerr_api_key
# Gotify Configuration
GOTIFY_URL=http://localhost:8080
GOTIFY_APP_TOKEN=your_gotify_app_token
GOTIFY_CLIENT_TOKEN=your_gotify_client_token # Optional, for receiving messages
- Configure Claude Desktop:
Important: Use full paths in your configuration to ensure Claude Desktop can find the executables and project directory.
{
"mcpServers": {
"yarr": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": ["C:\\path\\to\\yarr\\packages\\server\\dist\\index.js"],
"cwd": "C:\\path\\to\\yarr",
"transport": {
"type": "stdio"
},
"env": {
"NODE_ENV": "production",
"PROWLARR_URL": "http://localhost:9696",
"PROWLARR_API_KEY": "your_prowlarr_api_key",
"SONARR_URL": "http://localhost:8989",
"SONARR_API_KEY": "your_sonarr_api_key",
"OVERSEERR_URL": "http://localhost:5055",
"OVERSEERR_API_KEY": "your_overseerr_api_key",
"GOTIFY_URL": "http://localhost:8080",
"GOTIFY_APP_TOKEN": "your_gotify_app_token",
"GOTIFY_CLIENT_TOKEN": "your_gotify_client_token"
}
}
}
}
Note: Replace C:\\path\\to\\yarr with your actual project directory path.
Sonarr
// Series Management
sonarr:search - Search for TV shows
sonarr:list-series - List all monitored TV series
sonarr:series-details - Get detailed information about a series
sonarr:add-series - Add a new series to monitor
sonarr:monitor-season - Monitor or unmonitor a season
sonarr:list-profiles - List quality and language profiles
sonarr:upcoming - Get upcoming episodes
sonarr:queue - Get current download queue
sonarr:remove-from-queue - Remove item from download queue
Prowlarr
prowlarr:search - Search across all indexers
prowlarr:list-indexers - List configured indexers
prowlarr:indexer-stats - Get indexer performance stats
prowlarr:check-config - Validate Prowlarr connection
Overseerr
overseerr:search - Search for movies and TV shows
overseerr:request - Request a movie or TV show
overseerr:list-requests - List media requests
overseerr:update-request - Update request status
overseerr:trending - Get trending media with recommendations
overseerr:available - Get popular available media
overseerr:status - Get system status
Gotify
gotify:messages:list - List messages with pagination
gotify:messages:send - Send a new message
gotify:messages:delete - Delete a message by ID
gotify:messages:cleanup - Delete old messages
gotify:apps:list - List all applications
gotify:apps:create - Create a new application
gotify:clients:list - List all clients
gotify:clients:create - Create a new client
gotify:health - Check Gotify server health
gotify:stats - Get Gotify statistics