Media Server

A Model Context Protocol (MCP) server that provides AI assistants with tools to manage Radarr (movies), Sonarr (TV series), Plex media servers, and access TMDB data through natural language interactions.

Packages

This is a monorepo containing the following packages:

• @wyattjoh/media-server-mcp - The main MCP server
• @wyattjoh/radarr - Radarr API client library
• @wyattjoh/sonarr - Sonarr API client library
• @wyattjoh/tmdb - TMDB API client library
• @wyattjoh/plex - Plex API client library

Features

• Radarr Integration: Search, add, manage, and monitor movies
• Sonarr Integration: Search, add, manage, and monitor TV series
• Plex Integration: Browse libraries, search content, and manage Plex media server
• TMDB Integration: Advanced movie/TV discovery, external ID lookup, and comprehensive metadata
• Tool Configuration System: Reduce tool clutter with 6 profiles (18-70 tools) and branch-based filtering
• MCP Resources: Expose service configs and dynamic data (movies, series, collections, genres) as readable resources
• MCP Prompts: Built-in prompts for common workflows (add-movie, add-series, library-report, recommendations)
• Flexible Service Configuration: Each service is optional - configure any combination
• Type-Safe: Built with TypeScript for reliable operations
• Easy Setup: Install directly from JSR with a single deno run command

Installation

JSR (Recommended)

Add to your MCP servers configuration using the JSR package:

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@wyattjoh/media-server-mcp"],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "TMDB_API_KEY": "your-tmdb-api-key",
        "PLEX_URL": "http://localhost:32400",
        "PLEX_API_KEY": "your-plex-api-key",
        "TOOL_PROFILE": "default"
      }
    }
  }
}

Direct from GitHub

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": [
        "run",
        "--allow-all",
        "https://raw.githubusercontent.com/wyattjoh/media-server-mcp/main/packages/media-server-mcp/src/index.ts"
      ],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key"
      }
    }
  }
}

Quick Start

1. Configure at least one service in your MCP client's configuration:

Minimal Radarr-only Setup

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@wyattjoh/media-server-mcp"],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key"
      }
    }
  }
}

Minimal Sonarr-only Setup

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@wyattjoh/media-server-mcp"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key"
      }
    }
  }
}

Minimal TMDB-only Setup

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@wyattjoh/media-server-mcp"],
      "env": {
        "TMDB_API_KEY": "your-tmdb-api-key"
      }
    }
  }
}

2. Find your API keys:

   • Radarr: Settings → General → Security → API Key
   • Sonarr: Settings → General → Security → API Key
   • TMDB: Sign up at TMDB, go to Settings → API → Create API Key

   Important:

   • For TMDB, you'll need a free TMDB account and API key from their developer section.

3. Start using - Ask your AI assistant to manage your media library!

Configuration

Environment Variables

Variable	Description	Required
RADARR_URL	Base URL of your Radarr instance	Optional*
RADARR_API_KEY	API key for Radarr authentication	Optional*
SONARR_URL	Base URL of your Sonarr instance	Optional*
SONARR_API_KEY	API key for Sonarr authentication	Optional*
TMDB_API_KEY	TMDB API key for movie/TV metadata	Optional*
PLEX_URL	Base URL of your Plex instance	Optional*
PLEX_API_KEY	X-Plex-Token for Plex authentication	Optional*
MCP_AUTH_TOKEN	Authentication token for HTTP transport modes	Optional

*At least one service (Radarr, Sonarr, TMDB, or Plex) must be configured.

Example URLs

• Local Radarr: http://localhost:7878
• Local Sonarr: http://localhost:8989
• Remote with custom port: https://radarr.yourdomain.com:443

SSE Mode (HTTP Transport)

Deprecated: SSE transport is deprecated. Use Streamable HTTP (--http) instead.

By default, the MCP server runs in stdio mode for direct integration with MCP clients. However, you can also run it in SSE (Server-Sent Events) mode over HTTP for web-based integrations or debugging.

Running in SSE Mode

# Start server in SSE mode on port 3000 (default)
deno run --allow-all jsr:@wyattjoh/media-server-mcp --sse

# Or specify a custom port
deno run --allow-all jsr:@wyattjoh/media-server-mcp --sse --port 8080

Authentication Token

Important: SSE mode requires the MCP_AUTH_TOKEN environment variable for security. This token is used to authenticate HTTP requests via Bearer token authentication.

# Required for SSE mode
export MCP_AUTH_TOKEN="your-secure-random-token"

# Generate a secure token (example using openssl)
export MCP_AUTH_TOKEN=$(openssl rand -base64 32)

SSE Endpoints

When running in SSE mode, the server provides these endpoints:

• GET /sse - SSE event stream endpoint; the server assigns a session ID and sends the message endpoint URL via an SSE endpoint event (requires Bearer auth)
• POST /messages?sessionId=<id> - HTTP POST endpoint for client messages (requires Bearer auth)
• GET /health - Health check endpoint (no authentication required)

Example SSE Usage

# Set authentication token
export MCP_AUTH_TOKEN="your-secure-token"

# Start server in SSE mode
deno run --allow-all jsr:@wyattjoh/media-server-mcp --sse --port 3000

# Test health endpoint
curl http://localhost:3000/health

# Connect to SSE stream (requires Bearer token)
# The server assigns a session ID and sends it via an SSE event
curl -H "Authorization: Bearer your-secure-token" \
     http://localhost:3000/sse

Security Notes:

• Never expose SSE mode to the internet without proper authentication
• Use a strong, randomly generated MCP_AUTH_TOKEN
• The health endpoint (/health) is the only unauthenticated endpoint
• All other endpoints require valid Bearer token authentication

Streamable HTTP Mode (Recommended for Remote)

Streamable HTTP is the recommended transport for remote MCP server deployments. It uses a single /mcp endpoint with session management via the Mcp-Session-Id header, following the MCP 2025-03-26 specification.

Running in Streamable HTTP Mode

# Start server in Streamable HTTP mode on port 3000 (default)
deno run --allow-all jsr:@wyattjoh/media-server-mcp --http

# Specify a custom port and host
deno run --allow-all jsr:@wyattjoh/media-server-mcp --http --port 8080 --host 127.0.0.1

Endpoints

• POST /mcp - Send JSON-RPC requests (Initialize creates a session; subsequent requests require Mcp-Session-Id header)
• GET /mcp - Open SSE stream for server-initiated notifications (requires Mcp-Session-Id header)
• DELETE /mcp - Terminate a session (requires Mcp-Session-Id header)
• GET /health - Health check endpoint (no authentication required)

Authentication

Authentication via MCP_AUTH_TOKEN is optional but strongly recommended for any deployment accessible over a network. When set, all requests (except /health) must include a Authorization: Bearer <token> header.

# Set authentication token (recommended)
export MCP_AUTH_TOKEN=$(openssl rand -base64 32)

# Start server
deno run --allow-all jsr:@wyattjoh/media-server-mcp --http

Connecting from Claude Code

# Without authentication
claude mcp add --transport http media-server http://your-server:3000/mcp

# With authentication (set the token as a header)
claude mcp add --transport http media-server http://your-server:3000/mcp \
  --header "Authorization: Bearer your-secure-token"

Connecting from Claude.com

1. Go to Settings > Custom Connectors
2. Add a new MCP server with Transport type "Streamable HTTP"
3. Enter the URL: https://your-server:3000/mcp
4. If using authentication, configure the Bearer token

Security Best Practices

• Always use HTTPS in production — terminate TLS with a reverse proxy (nginx, Caddy, etc.) in front of the MCP server
• Set MCP_AUTH_TOKEN with a strong, randomly generated value for any network-accessible deployment
• Bind to specific interfaces using --host to limit which network interfaces accept connections (e.g., --host 127.0.0.1 for localhost only)
• Use a reverse proxy for rate limiting, request size limits, and TLS termination
• Restrict network access using firewall rules or VPN to limit who can reach the server
• CORS: Both SSE and Streamable HTTP transports set Access-Control-Allow-Origin: * to support MCP clients across environments. Bearer tokens in Authorization headers are not automatically sent by browsers, but if tighter origin control is needed, configure CORS restrictions in your reverse proxy

Tool Configuration System

The Media Server MCP includes a powerful tool filtering system that allows you to control which tools are exposed to your AI assistant. This helps reduce tool clutter and focus on the functionality you need.

Tool Organization

Tools are organized into 6 logical branches:

Branch	Description	Tool Count	Purpose
discovery-add	Core discovery and adding functionality	18 tools	Finding and adding new content
library-management	Managing existing content	11 tools	Organizing your library
system-maintenance	Health checks and maintenance	10 tools	System administration
download-management	Queue and download operations	7 tools	Download monitoring
metadata-enrichment	Advanced TMDB research features	16 tools	Deep content research
advanced-search	External ID lookups and specialized searches	7 tools	Power user features

Predefined Profiles

Choose from 6 predefined profiles that combine different tool branches:

Profile	Branches Included	Total Tools	Best For
default (default)	discovery-add	18 tools	Most users - essential discovery and adding
minimal	discovery-add	18 tools	Same as default
curator	discovery-add + library-management	29 tools	Managing existing content
maintainer	curator + system-maintenance	39 tools	System administrators
power-user	All except advanced-search	63 tools	Advanced users
full	All branches	70 tools	Complete functionality

Configuration Methods

1. Environment Variables (Recommended)

Add these variables to your MCP server configuration:

{
  "mcpServers": {
    "media-server": {
      "command": "deno",
      "args": ["run", "--allow-all", "jsr:@wyattjoh/media-server-mcp"],
      "env": {
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "TOOL_PROFILE": "curator",
        "TOOL_BRANCHES": "download-management"
      }
    }
  }
}

Available Environment Variables:

Variable	Description	Example Values
TOOL_PROFILE	Select a predefined profile	default, curator, power-user, full
TOOL_BRANCHES	Add specific branches (comma-separated)	library-management,system-maintenance
TOOL_EXCLUDE	Exclude specific tools (comma-separated)	radarr_delete_movie,sonarr_delete_series
TOOL_INCLUDE	Include specific tools (overrides other settings)	radarr_get_health,sonarr_get_health
TOOL_CONFIG_PATH	Path to JSON configuration file	./tools.config.json

2. JSON Configuration File

For advanced configuration, create a JSON file and reference it with TOOL_CONFIG_PATH:

{
  "toolProfile": "curator",
  "enabledBranches": ["download-management", "system-maintenance"],
  "customOverrides": {
    "exclude": [
      "radarr_delete_movie",
      "sonarr_delete_series"
    ],
    "include": [
      "radarr_get_health",
      "sonarr_get_health"
    ]
  }
}

Configuration Precedence

Settings are applied in this order (later settings override earlier ones):

1. Default Profile: discovery-add tools only (18 tools)
2. JSON Configuration File: Applied if TOOL_CONFIG_PATH is set
3. Environment Variables: Override JSON settings
4. Custom Overrides: TOOL_EXCLUDE and TOOL_INCLUDE applied last

Common Configuration Examples

Minimal Setup (Default)

# No tool configuration needed - uses default profile
# Result: 18 essential discovery and add tools

Content Curator

TOOL_PROFILE=curator
# Result: 29 tools (discovery + library management)

System Administrator

TOOL_PROFILE=maintainer
TOOL_INCLUDE=radarr_disk_scan,sonarr_disk_scan
# Result: 41 tools (maintainer profile + disk scanning)

Power User with Restrictions

TOOL_PROFILE=power-user
TOOL_EXCLUDE=radarr_delete_movie,sonarr_delete_series,sonarr_disk_scan
# Result: 60 tools (power-user minus dangerous operations)

Discovery Only (TMDB + Search)

TOOL_PROFILE=default
TOOL_EXCLUDE=radarr_add_movie,sonarr_add_series
# Result: 16 tools (discovery without adding capabilities)

Full Access

TOOL_PROFILE=full
# Result: 70 tools (all available functionality)

Tool Configuration Debugging

The server logs the active configuration on startup:

[INFO] Tool Configuration:
  Profile: curator
  Additional Branches: download-management
  Excluded Tools: radarr_delete_movie, sonarr_delete_series
  Total Enabled Tools: 36

This helps verify your configuration is working as expected.

Available Tools

Radarr Tools (when configured)

Movie Management

• radarr_search_movie - Search for movies in The Movie Database
• radarr_add_movie - Add a movie to your library
• radarr_get_movies - List all movies in your library (supports filtering by title, genres, year range, monitored status, file availability, quality profile, tags, minimum availability, and TMDB ID)
• radarr_get_movie - Get details of a specific movie
• radarr_delete_movie - Remove a movie from your library

Queue and Downloads

• radarr_get_queue - View current download queue
• radarr_search_movie_releases - Search for releases of a specific movie

System Management

• radarr_get_configuration - Get configuration including quality profiles, root folders, and tags
• radarr_get_system_status - Get system information
• radarr_get_health - Check system health
• radarr_refresh_movie - Refresh movie metadata
• radarr_update_movie - Update a movie's settings (quality profile, monitoring, etc.)
• radarr_refresh_all_movies - Refresh metadata for all movies in the library
• radarr_disk_scan - Rescan all movie folders for new/missing files

Wanted/Missing and Quality Management

• radarr_get_wanted_missing - Get movies that are monitored but not yet downloaded
• radarr_get_wanted_cutoff - Get movies downloaded but below quality cutoff
• radarr_get_calendar - Get upcoming movie releases within a date range

History and Troubleshooting

• radarr_get_history - Get paginated download history with event type filtering
• radarr_get_movie_history - Get download history for a specific movie
• radarr_mark_failed - Mark a download as failed to trigger re-grab

Interactive Release Management

• radarr_get_releases - Browse available releases from indexers for a movie
• radarr_grab_release - Download a specific release
• radarr_search_all_missing - Trigger search for all missing movies at once
• radarr_delete_queue_item - Remove a stuck/failed item from the queue
• radarr_grab_queue_item - Force download a queue item

Sonarr Tools (when configured)

Series Management

• sonarr_search_series - Search for TV series
• sonarr_add_series - Add a TV series to your library
• sonarr_get_series - List all series in your library (supports filtering by title, genres, year range, monitored status, network, series type, quality profile, tags, status, and TMDB ID)
• sonarr_get_series_by_id - Get details of a specific series
• sonarr_delete_series - Remove a series from your library

Episode Management

• sonarr_get_episodes - Get episodes for a series
• sonarr_get_episode - Get details of a specific episode by ID
• sonarr_update_episode_monitoring - Change episode monitoring status
• sonarr_get_calendar - View upcoming episodes
• sonarr_search_series_episodes - Search for all episodes of a series
• sonarr_search_season - Search for episodes of a specific season
• sonarr_search_episodes - Search for specific episodes by IDs

Queue and Downloads

• sonarr_get_queue - View current download queue

System Management

• sonarr_get_configuration - Get configuration including quality profiles and root folders
• sonarr_get_system_status - Get system information
• sonarr_get_health - Check system health
• sonarr_refresh_series - Refresh series metadata
• sonarr_update_series - Update a series' settings (quality profile, monitoring, etc.)
• sonarr_refresh_all_series - Refresh metadata for all series in the library
• sonarr_disk_scan - Rescan all series folders for new/missing files

Wanted/Missing and Quality Management

• sonarr_get_wanted_missing - Get episodes that are monitored but not yet downloaded
• sonarr_get_wanted_cutoff - Get episodes downloaded but below quality cutoff

History and Troubleshooting

• sonarr_get_history - Get paginated download history with event type filtering
• sonarr_get_series_history - Get download history for a specific series
• sonarr_mark_failed - Mark a download as failed to trigger re-grab

Interactive Release Management

• sonarr_get_releases - Browse available releases from indexers for an episode
• sonarr_grab_release - Download a specific release
• sonarr_search_all_missing - Trigger search for all missing episodes at once
• sonarr_delete_queue_item - Remove a stuck/failed item from the queue
• sonarr_grab_queue_item - Force download a queue item

TMDB Tools (when configured)

Search and Discovery

• tmdb_search_movies - Search for movies on TMDB by title
• tmdb_search_tv - Search for TV shows on TMDB by title
• tmdb_search_multi - Search for movies, TV shows, and people in a single request
• tmdb_get_popular_movies - Get popular movies
• tmdb_discover_movies - Discover movies based on various criteria (genre, year, rating, etc.)
• tmdb_discover_tv - Discover TV shows based on various criteria

Trending Content

• tmdb_get_trending - Get trending movies, TV shows, or people by time window (day/week)

Movie Lists

• tmdb_get_now_playing_movies - Get movies currently playing in theaters
• tmdb_get_top_rated_movies - Get top rated movies
• tmdb_get_upcoming_movies - Get upcoming movie releases

TV Show Lists

• tmdb_get_popular_tv - Get popular TV shows
• tmdb_get_top_rated_tv - Get top rated TV shows
• tmdb_get_on_the_air_tv - Get TV shows currently on the air
• tmdb_get_airing_today_tv - Get TV shows airing today

Content Details

• tmdb_get_movie_details - Get detailed information about a specific movie
• tmdb_get_tv_details - Get detailed information about a specific TV show

Recommendations and Similar Content

• tmdb_get_movie_recommendations - Get movie recommendations based on a specific movie
• tmdb_get_tv_recommendations - Get TV show recommendations based on a specific show
• tmdb_get_similar_movies - Get movies similar to a specific movie
• tmdb_get_similar_tv - Get TV shows similar to a specific show

People Discovery

• tmdb_search_people - Search for people (actors, directors, etc.)
• tmdb_get_popular_people - Get popular people in the entertainment industry
• tmdb_get_person_details - Get detailed information about a specific person
• tmdb_get_person_movie_credits - Get a person's movie credits
• tmdb_get_person_tv_credits - Get a person's TV show credits

Collections and Keywords

• tmdb_search_collections - Search for movie collections
• tmdb_get_collection_details - Get details about a specific movie collection
• tmdb_search_keywords - Search for keywords
• tmdb_get_movies_by_keyword - Get movies associated with a specific keyword

Certifications and Watch Providers

• tmdb_get_certifications - Get movie or TV certifications by country
• tmdb_get_watch_providers - Get watch provider information for a movie or TV show

External ID Integration

• tmdb_find_by_external_id - Find TMDB content by external ID (TVDB ID, etc.)

Configuration and Metadata

• tmdb_get_genres - Get list of available genres for movies or TV shows
• tmdb_get_configuration - Get TMDB API configuration including image base URLs
• tmdb_get_countries - Get list of countries used in TMDB
• tmdb_get_languages - Get list of languages used in TMDB

Cast and Crew Information

• tmdb_get_movie_credits - Get cast and crew for a movie
• tmdb_get_tv_credits - Get cast and crew for a TV show

Plex Tools (when configured)

System Information

• plex_get_capabilities - Get Plex server capabilities, version, and system information

Library Management

• plex_get_libraries - List all media libraries available on the Plex server
• plex_refresh_library - Trigger a refresh of a specific library to scan for new content
• plex_get_library_items - Browse and filter items in a library section (supports filtering by studio, genre, year, and sorting)

Search and Discovery

• plex_search - Search across all Plex libraries for movies, TV shows, and other content with optional type filters
• plex_get_metadata - Get detailed metadata for a specific movie, TV show, or other media item

Collection Management

• plex_get_collections - List all collections in a library section
• plex_get_collection_items - Get all items in a specific collection
• plex_create_collection - Create a new collection with initial items
• plex_add_to_collection - Add items to an existing collection
• plex_remove_from_collection - Remove a single item from a collection
• plex_delete_collection - Delete an entire collection

Usage Examples

Natural Language Requests

With this MCP server configured, you can ask your AI assistant:

• "Add the movie Inception to my Radarr library"
• "Show me what TV series are in my Sonarr queue"
• "What episodes of Breaking Bad are airing this week?"
• "Add The Office to my TV library and monitor all seasons"
• "Find movies on TMDB similar to The Dark Knight from 2020-2024"
• "Discover highly-rated sci-fi TV shows on TMDB"
• "Get the Radarr system status and health"

API Examples

Adding a Movie

{
  "tool": "radarr_add_movie",
  "arguments": {
    "tmdbId": 550,
    "title": "Fight Club",
    "year": 1999,
    "qualityProfileId": 1,
    "rootFolderPath": "/movies",
    "minimumAvailability": "released",
    "monitored": true,
    "searchForMovie": true
  }
}

Adding a TV Series

{
  "tool": "sonarr_add_series",
  "arguments": {
    "tvdbId": 78804,
    "title": "Breaking Bad",
    "qualityProfileId": 1,
    "rootFolderPath": "/tv",
    "monitored": true,
    "seasonFolder": true,
    "seriesType": "standard"
  }
}

Discovering Movies on TMDB

{
  "tool": "tmdb_discover_movies",
  "arguments": {
    "with_genres": "28,878",
    "vote_average_gte": 7.0,
    "primary_release_year": 2023,
    "sort_by": "popularity.desc"
  }
}

Troubleshooting

Common Issues

No Tools Available

• Ensure at least one service is configured with valid environment variables
• Check that URLs are accessible and API keys are correct
• Verify the MCP server is starting without errors

Connection Refused

• Verify Radarr/Sonarr URLs are correct and accessible
• Check that the services are running
• Ensure no firewall is blocking the connections

Unauthorized/403 Errors

• Verify API keys are correct and haven't expired
• Check that API access is enabled in service settings

Tool Configuration Issues

• Too many/few tools: Check your TOOL_PROFILE setting or use TOOL_BRANCHES to add specific functionality
• Missing expected tools: Verify the tool is included in your profile/branches using the startup logs
• Invalid profile error: Use one of the valid profiles: default, minimal, curator, maintainer, power-user, full
• JSON config not loading: Check that TOOL_CONFIG_PATH points to a valid file and has correct JSON syntax

Debug Mode

Check MCP server logs for connection status and tool configuration on startup. The server will:

• Test each configured service and report connection results
• Log the active tool configuration showing profile, branches, and total tool count
• Report any configuration parsing errors

Development

Local Development Setup

1. Clone this repository:

git clone https://github.com/wyattjoh/media-server-mcp.git
cd media-server-mcp

2. Create environment configuration:

cp .env.example .env
# Edit .env with your service URLs and API keys

3. Run the server:

deno task dev

Available Scripts

# Development with hot reload
deno task dev

# Production run  
deno task start

# Type checking
deno check

# Code formatting
deno fmt

# Linting
deno lint

Project Structure

src/
├── index.ts              # Main MCP server
├── clients/
│   ├── radarr.ts         # Radarr API client
│   ├── sonarr.ts         # Sonarr API client
│   └── tmdb.ts           # TMDB API client
├── tools/
│   ├── radarr-tools.ts   # Radarr MCP tools
│   ├── sonarr-tools.ts   # Sonarr MCP tools  
│   └── tmdb-tools.ts     # TMDB MCP tools
├── utils/
│   └── filters.ts        # Filtering and sorting utilities
└── types/
    ├── radarr.ts         # Radarr type definitions
    ├── sonarr.ts         # Sonarr type definitions
    ├── tmdb.ts           # TMDB type definitions
    ├── mcp.ts            # MCP-specific types
    ├── filters.ts        # Filter and sort type definitions
    └── validation.ts     # Validation utilities

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE.md file for details.

Acknowledgments

• Built on the Model Context Protocol
• Integrates with Radarr, Sonarr, and TMDB
• Uses The Movie Database API for comprehensive movie and TV metadata
• Uses the Deno runtime for modern JavaScript/TypeScript execution