Media Library Management Context Protocol Server

A Python implementation of the Model Context Protocol (MCP) designed to expose managed media libraries—specifically movies indexed by Radarr and series tracked by Sonarr—to large language models like Claude.

Core Functionality

This component utilizes FastMCP to establish a standardized communication channel, enabling AI agents to programmatically inspect, filter, and retrieve details concerning owned or tracked movies and TV programs. Filtering capabilities include temporal aspects (release year) and consumption status (e.g., watched/unwatched).

Key Capabilities

• Standardized Access: Adheres to the MCP specification for reliable integration with AI assistants.
• Film Data: Direct interfacing with the Radarr endpoint.
• TV Data: Direct interfacing with the Sonarr endpoint.
• Granular Filtering: Supports complex queries based on attributes such as publication year, viewing progress, actor presence, and download status.
• Client Compatibility: Optimized for use with the Claude Desktop MCP client.
• Deployment: Features an interactive script for simplified initial configuration.

Setup Procedure

From Source Distribution

1. Clone the repository source code: bash git clone https://github.com/yourusername/radarr-sonarr-mcp.git cd radarr-sonarr-mcp-python

2. Install the package in editable mode: bash pip install -e .

Distribution Installation (Future Release)

bash pip install media-library-mcp-tool

Initial Execution

1. Run the setup utility to define connection parameters: bash radarr-sonarr-mcp setup-config

   You will be prompted for server addresses, port numbers, and required API credentials for both media managers.

2. Activate the MCP service listener: bash radarr-sonarr-mcp launch-server

3. In your MCP-enabled application (e.g., Claude Desktop):

   • Navigate to Connection Settings or MCP Server Management.
   • Register a new endpoint, typically pointing to http://localhost:3000 (or the port specified during setup).

Configuration Parameters

The system relies on a configuration file (typically config.json) populated by the setup wizard. Essential parameters include:

• Network address (ip) and port for the host system.
• Radarr authentication token (apiKey) and API path structure.
• Sonarr authentication token (apiKey) and API path structure.
• The local port on which the MCP server will listen for AI agent requests.

Exposed MCP Functions

This server exposes the following functional interfaces to the connected client:

Movie Operations

• fetch_all_movies: Retrieves the entire film catalog, supporting attribute-based subsetting.
• find_movie_by_name: Executes a search for a motion picture using its title.
• retrieve_movie_record: Fetches exhaustive metadata for a known movie identifier.

Series Operations

• fetch_all_series: Retrieves the catalog of tracked television programs, filterable.
• find_series_by_name: Executes a search for a television program using its title.
• retrieve_series_record: Fetches exhaustive metadata for a known TV series identifier.
• get_series_episodes_list: Obtains all episode entries associated with a specific series ID.

Query Parameters Supported

Tools frequently support modifiers such as:

• release_year: Limiting results to a specific calendar year.
• viewed_status: Boolean flag for completion status.
• download_status: Boolean flag indicating download completion status.
• on_watchlist: Boolean flag indicating tracking status.
• starring_actor: Filtering by cast member names.

Example AI Interactions

Agents connected to this service can respond to queries like:

• "Identify all documentary films released in 2019 that I have not yet marked as watched."
• "List all ongoing television programs featuring Emma Stone."
• "Are there any unwatched episodes for the series 'Foundation'?"

Key Dependencies

• Python version 3.7 or newer.
• The FastMCP framework library.
• The requests library for external HTTP communication.
• Pydantic for data schema validation.

Security and Operation Notes

It is strongly advised to deploy this service within a secure, trusted network segment (e.g., local LAN). The implementation of status checks (watched/watchlist) is contingent upon the specific data structures returned by the configured Radarr/Sonarr instances.