Sonarr MCP Server
About
# Sonarr MCP Server [](https://github.com/Jacques-Murray/sonarr-mcp-server/actions/workflows/ci-cd.yml) [
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Sonarr MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
⚙️ Configuration
- Quality Profiles: View and manage quality settings
- Root Folders: Configure storage locations
- Indexer Status: Monitor search providers
- Custom Formats: Access advanced quality configurations
Prerequisites
- Node.js: Version 18.0.0 or higher
- npm: Version 8.0.0 or higher (comes with Node.js)
- Sonarr: Version 4.x running and accessible
- API Access: Valid Sonarr API key with appropriate permissions
When adding new Sonarr functionality:
1. Define the tool schema in src/tools/index.ts
2. Implement the handler with proper error handling
3. Add comprehensive tests in tests/tools.test.ts
4. Update documentation with usage examples
5. Test with real Sonarr instance
- Jest - Comprehensive testing framework
- ESLint - Code quality and style enforcement
- GitHub Actions - CI/CD automation
- Docker - Containerization and deployment
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"sonarr mcp server": {
"sonarr-mcp-server": {
"command": "docker",
"args": [
"pull",
"ghcr.io/jacques-murray/sonarr-mcp-server:latest"
]
}
}
}
}McpServers
{
"sonarr-mcp-server": {
"command": "docker",
"args": [
"pull",
"ghcr.io/jacques-murray/sonarr-mcp-server:latest"
]
}
}
A comprehensive Model Context Protocol (MCP) server implementation for Sonarr, enabling AI assistants to manage TV series through natural language interactions.
Table of Contents
- Overview
- Features
- Installation
- Prerequisites
- Local Installation
- Docker Installation
- Usage
- Running the MCP Server
- Integrating with AI Assistants
- API Documentation
- MCP Tools
- MCP Resources
- Configuration
- Development Setup
- Docker Usage
- CI/CD Information
- Troubleshooting
- Contributing
- License
Overview
This MCP server provides AI assistants with the ability to:
- Manage TV Series: Add, update, remove, and monitor series in your Sonarr collection
- Episode Operations: Search for episodes, manage downloads, and monitor file status
- Queue Management: View and control the download queue
- System Monitoring: Check system health, disk space, and activity
- Calendar Integration: View upcoming episodes and air dates
- Configuration Access: Manage quality profiles, root folders, and settings
Features
🎬 Series Management
- Add Series: Search and add new TV series with customizable monitoring options
- List Series: View your collection with filtering by status, monitoring, and search terms
- Update Series: Modify series settings, quality profiles, and monitoring status
- Remove Series: Delete series with optional file cleanup
📺 Episode Operations
- Search Episodes: Trigger searches for missing episodes across all or specific series
- Monitor Episodes: Toggle monitoring for individual episodes or seasons
- Episode Status: Check file availability and download progress
- Season Management: Bulk operations on entire seasons
📥 Download Management
- Queue Monitoring: Real-time view of download progress and status
- Queue Control: Remove stuck downloads and manage queue items
- Download History: Track successful downloads and failed attempts
- Release Management: View available releases and trigger manual downloads
🖥️ System Information
- System Status: Monitor Sonarr health, version, and runtime information
- Disk Space: Track storage usage and available space
- Activity Monitoring: View current operations and system activity
- Calendar View: Upcoming episodes and air dates
⚙️ Configuration
- Quality Profiles: View and manage quality settings
- Root Folders: Configure storage locations
- Indexer Status: Monitor search providers
- Custom Formats: Access advanced quality configurations
Installation
Prerequisites
- Node.js: Version 18.0.0 or higher
- npm: Version 8.0.0 or higher (comes with Node.js)
- Sonarr: Version 4.x running and accessible
- API Access: Valid Sonarr API key with appropriate permissions
Local Installation
1. Clone the repository:
git clone https://github.com/Jacques-Murray/sonarr-mcp-server.git
cd sonarr-mcp-server
1. Install dependencies:
npm install
1. Configure environment variables:
cp .env.example .env
Edit .env with your Sonarr settings:
```env
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
