Sonarr & Radarr MCP Server

A secure, production-ready Model Context Protocol (MCP) server for interacting with Sonarr and Radarr APIs. This server enables Claude to query your media library, check recent additions, view upcoming releases, and perform basic management tasks.

Features

Sonarr

• Get recently added TV series
• View upcoming episode calendar
• Search series in your library
• Check system status and disk space
• View download queue
• Refresh series metadata
• Trigger episode searches

Radarr

• Get recently added movies
• View upcoming movie releases
• Search movies in your library
• Check system status and disk space
• View download queue
• Refresh movie metadata
• Trigger movie searches

Security Features

This MCP server is built with security as a priority:

• Non-root container execution: Runs as user ID 1000 (non-root)
• Read-only root filesystem: Container filesystem is immutable
• No privilege escalation: Container cannot gain additional privileges
• Dropped capabilities: All Linux capabilities dropped
• Secrets management: API keys stored in Kubernetes secrets
• Network policies: Restricts network access to only necessary services
• Resource limits: CPU and memory limits prevent resource exhaustion
• Secure defaults: Follows security best practices from the ground up

Prerequisites

• Docker (for containerization)
• Kubernetes cluster (for deployment)
• Sonarr instance with API access
• Radarr instance with API access
• Python 3.12+ (for local development)

Quick Start

1. Clone and Configure

git clone <your-repo-url>
cd mcp-servarr

2. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your actual values:

# Sonarr Configuration
SONARR_URL=http://your-sonarr-host:8989
SONARR_API_KEY=your-sonarr-api-key

# Radarr Configuration
RADARR_URL=http://your-radarr-host:7878
RADARR_API_KEY=your-radarr-api-key

Finding your API keys:

• Sonarr: Settings → General → Security → API Key
• Radarr: Settings → General → Security → API Key

3. Build the Docker Image

docker build -t mcp-servarr:latest .

4. Test Locally with Docker Compose

docker-compose up

Kubernetes Deployment

1. Update Secrets

Edit k8s/deployment.yaml and replace the placeholder API keys in the Secret:

stringData:
  SONARR_URL: "http://sonarr.media.svc.cluster.local:8989"
  SONARR_API_KEY: "your-actual-sonarr-api-key"
  RADARR_URL: "http://radarr.media.svc.cluster.local:7878"
  RADARR_API_KEY: "your-actual-radarr-api-key"

Security Note: For production, use kubectl create secret instead of storing secrets in YAML:

kubectl create secret generic mcp-servarr-secrets \
  --namespace=mcp-servarr \
  --from-literal=SONARR_URL='http://sonarr:8989' \
  --from-literal=SONARR_API_KEY='your-key' \
  --from-literal=RADARR_URL='http://radarr:7878' \
  --from-literal=RADARR_API_KEY='your-key'

2. Deploy to Kubernetes

kubectl apply -f k8s/deployment.yaml

3. Verify Deployment

kubectl get pods -n mcp-servarr
kubectl logs -n mcp-servarr deployment/mcp-servarr

Connecting to Claude

To use this MCP server with Claude Desktop, add it to your MCP settings:

Using Docker

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-servarr": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file", "/path/to/your/.env",
        "mcp-servarr:latest"
      ]
    }
  }
}

Using Python (Development)

{
  "mcpServers": {
    "mcp-servarr": {
      "command": "python",
      "args": [
        "/path/to/mcp-servarr/src/server.py"
      ],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-key"
      }
    }
  }
}

Usage Examples

Once connected to Claude, you can ask questions like:

• "What TV shows were added to Sonarr this week?"
• "What movies are coming out in the next 30 days?"
• "Search for Breaking Bad in my library"
• "What's currently downloading in Radarr?"
• "Show me Sonarr's system status"
• "Refresh the metadata for series ID 123"

API Reference

Environment Variables

Variable	Required	Default	Description
SONARR_URL	No*	-	Sonarr base URL (e.g., http://sonarr:8989)
SONARR_API_KEY	No*	-	Sonarr API key
RADARR_URL	No*	-	Radarr base URL (e.g., http://radarr:7878)
RADARR_API_KEY	No*	-	Radarr API key
REQUEST_TIMEOUT	No	30	HTTP request timeout in seconds

*At least one service (Sonarr or Radarr) must be configured

Available Tools

Sonarr Tools

• sonarr_get_recent_series - Get recently added series
• sonarr_get_calendar - Get upcoming episodes
• sonarr_search_series - Search for series
• sonarr_get_system_status - Get system status
• sonarr_get_queue - Get download queue
• sonarr_refresh_series - Refresh series metadata
• sonarr_search_episodes - Search for missing episodes

Radarr Tools

• radarr_get_recent_movies - Get recently added movies
• radarr_get_calendar - Get upcoming releases
• radarr_search_movies - Search for movies
• radarr_get_system_status - Get system status
• radarr_get_queue - Get download queue
• radarr_refresh_movie - Refresh movie metadata
• radarr_search_movie - Search for a movie

Development

Local Development Setup

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Run the server:

export SONARR_URL=http://localhost:8989
export SONARR_API_KEY=your-key
export RADARR_URL=http://localhost:7878
export RADARR_API_KEY=your-key
python src/server.py

Testing

Test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector python src/server.py

Troubleshooting

Connection Issues

Problem: Cannot connect to Sonarr/Radarr

Solutions:

• Verify URLs are correct (include http:// or https://)
• Check API keys are valid
• Ensure Sonarr/Radarr are accessible from the container
• Check network policies in Kubernetes

Permission Errors

Problem: Container fails with permission errors

Solutions:

• Verify the container runs as non-root (UID 1000)
• Check volume mount permissions
• Ensure read-only filesystem is properly configured

API Rate Limiting

Problem: Getting rate limited by APIs

Solutions:

• Increase REQUEST_TIMEOUT if requests are timing out
• Reduce frequency of queries
• Check Sonarr/Radarr logs for issues

Security Considerations

Production Deployment Checklist

• [ ] Use Kubernetes Secrets for API keys (not ConfigMaps)
• [ ] Enable Pod Security Standards (restricted profile)
• [ ] Configure network policies to limit egress traffic
• [ ] Set appropriate resource limits
• [ ] Enable audit logging
• [ ] Use private container registry
• [ ] Scan images for vulnerabilities
• [ ] Rotate API keys regularly
• [ ] Use TLS for Sonarr/Radarr connections
• [ ] Implement monitoring and alerting

API Key Security

Never commit API keys to version control!

For production:

1. Use Kubernetes secrets
2. Consider using a secrets manager (Vault, Sealed Secrets, etc.)
3. Rotate keys regularly
4. Use separate API keys for different environments
5. Enable API key authentication logging in Sonarr/Radarr

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation
• Ensure security best practices
• Test in both Docker and Kubernetes

License

MIT License - See LICENSE file for details

Support

For issues, questions, or contributions, please open an issue on GitHub.

Acknowledgments

• Built with the Model Context Protocol SDK
• Uses Sonarr API
• Uses Radarr API