Jellyfin Mcp

Jellyfin Mcp

CLI or API | MCP | Agent

Version: 1.0.1

> Documentation — Installation, deployment, usage across the MCP, API, and A2A > agent interfaces, and guidance for provisioning the Jellyfin media server are > maintained in the official documentation.

---

Table of Contents

• [Overview](#overview)
• [Key Features](#key-features)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [CLI or API](#cli-or-api)
• [MCP Integration](#mcp)
• [Available MCP Tools](#available-mcp-tools)
• [MCP Configuration Examples](#mcp-configuration-examples)
• [Agent Capabilities](#agent)
• [Running the Agent CLI](#running-the-agent-cli)
• [Docker Compose Orchestration](#docker-compose-orchestration)
• [Security & Governance](#security--governance)
• [Documentation](#documentation)
• [Contribute](#contribute)

---

Overview

Jellyfin Mcp is a production-grade Agent and Model Context Protocol (MCP) server designed to interface directly with Jellyfin MCP Server for Agentic AI!.

---

Quick Start

1. Installation

Install the package directly from PyPI:

uv pip install jellyfin-mcp[all]

2. Configure Environment

Set up your connection keys and Jellyfin host details (see .env.example for comprehensive list):

export JELLYFIN_URL="http://localhost:8096"
export JELLYFIN_API_KEY="your_api_key_here"

3. Run the MCP Server

Launch the server over standard standard I/O (stdio) transport:

jellyfin-mcp

4. Run the Agent CLI

To launch the interactive Graph Agent terminal interface:

jellyfin-agent --provider openai --model-id gpt-4o

---

---

Key Features

• Consolidated Action-Routed MCP Tools: Minimizes token overhead and eliminates tool bloat in LLM contexts by grouping methods into optimized, togglable tool modules.
• Enterprise-Grade Security: Comprehensive support for Eunomia policies, OIDC token delegation, and granular execution context tracking.
• Integrated Graph Agent: Built-in Pydantic AI agent supporting the Agent Control Protocol (ACP) and standard Web interfaces (AG-UI).
• Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and native Langfuse tracing.

---

CLI or API

This agent wraps the Jellyfin MCP Server for Agentic AI! API. You can interact with it programmatically or via its integrated execution entrypoints.

Detailed instructions on how to use the underlying API wrappers, extended schema bindings, and developer SDK references are maintained in [docs/index.md](docs/index.md).

---

MCP

This server utilizes dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Available MCP Tools

Auto-generated from the live MCP server — do not edit by hand.

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

| MCP Tool | Toggle Env Var | Description | |----------|----------------|-------------| | jellyfin_library | CONDENSED_JELLYFINTOOL | Execute library searches, items, collection updates, and catalog queries dynamically. | | jellyfin_media | CONDENSED_JELLYFINTOOL | Execute media playback, stream, artist, playlist, and audio/video queries dynamically. | | jellyfin_system | CONDENSED_JELLYFINTOOL | Execute administrative actions, system status, configurations, backups, and user management. |

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

368 per-operation tools — one per public API method (click to expand)

| MCP Tool | Toggle Env Var | Description | |----------|----------------|-------------| | jellyfin_add_item_to_playlist | MEDIA_CLIENTTOOL | Adds items to a playlist. | | jellyfin_add_listing_provider | MEDIA_CLIENTTOOL | Adds a listings provider. | | jellyfin_add_media_path | LIBRARY_CLIENTTOOL | Add a media path to a library. | | jellyfin_add_to_collection | LIBRARY_CLIENTTOOL | Adds items to a collection. | | jellyfin_add_tuner_host | MEDIA_CLIENTTOOL | Adds a tuner host. | | jellyfin_add_user_to_session | USER_CLIENTTOOL | Adds an additional user to a session. | | jellyfin_add_virtual_folder | LIBRARY_CLIENTTOOL | Adds a virtual folder. | | jellyfin_apply_search_criteria | LIBRARY_CLIENTTOOL | Applies search criteria to an item and refreshes metadata. | | jellyfin_authenticate_user_by_name | USER_CLIENTTOOL | Authenticates a user by name. | | jellyfin_authenticate_with_quick_connect | USER_CLIENTTOOL | Authenticates a user with quick connect. | | jellyfin_authorize_quick_connect | USER_CLIENTTOOL | Authorizes a pending quick connect request. | | jellyfin_cancel_package_installation | LIBRARY_CLIENTTOOL | Cancels a package installation. | | jellyfin_cancel_series_timer | MEDIA_CLIENTTOOL | Cancels a live tv series timer. | | jellyfin_cancel_timer | MEDIA_CLIENTTOOL | Cancels a live tv timer. | | jellyfin_close_live_stream | MEDIA_CLIENTTOOL | Closes a media source. | | jellyfin_complete_wizard | LIBRARY_CLIENTTOOL | Completes the startup wizard. | | jellyfin_create_backup | SYSTEM_CLIENTTOOL | Creates a new Backup. | | jellyfin_create_collection | LIBRARY_CLIENTTOOL | Creates a new collection. | | jellyfin_create_key | SYSTEM_CLIENTTOOL | Create a new api key. | | jellyfin_create_playlist | MEDIA_CLIENTTOOL | Creates a new playlist. | | jellyfin_create_series_timer | MEDIA_CLIENTTOOL | Creates a live tv series timer. | | jellyfin_create_timer | MEDIA_CLIENTTOOL | Creates a live tv timer. | | jellyfin_create_user_by_name | USER_CLIENTTOOL | Creates a user. | | jellyfin_delete_alternate_sources | MEDIA_CLIENTTOOL | Removes alternate video sources. | | jellyfin_delete_custom_splashscreen | SYSTEM_CLIENTTOOL | Delete a custom splashscreen. | | jellyfin_delete_device | USER_CLIENTTOOL | Deletes a device. | | jellyfin_delete_item | LIBRARY_CLIENTTOOL | Deletes an item from the library and filesystem. | | jellyfin_delete_item_image | LIBRARY_CLIENTTOOL | Delete an item's image. | | jellyfin_delete_item_image_by_index | LIBRARY_CLIENTTOOL | Delete an item's image. | | jellyfin_delete_items | LIBRARY_CLIENTTOOL | Deletes items from the library and filesystem. | | jellyfin_delete_listing_provider | MEDIA_CLIENTTOOL | Delete listing provider. | | jellyfin_delete_lyrics | MEDIA_CLIENTTOOL | Deletes an external lyric file. | | jellyfin_delete_recording | MEDIA_CLIENTTOOL | Deletes a live tv recording. | | jellyfin_delete_subtitle | MEDIA_CLIENTTOOL | Deletes an external subtitle file. | | jellyfin_delete_tuner_host | MEDIA_CLIENTTOOL | Deletes a tuner host. | | jellyfin_delete_user | USER_CLIENTTOOL | Deletes a user. | | jellyfin_delete_user_image | USER_CLIENTTOOL | Delete the user's image. | | jellyfin_delete_user_item_rating | USER_CLIENTTOOL | Deletes a user's saved personal rating for an item. | | jellyfin_disable_plugin | SYSTEM_CLIENTTOOL | Disable a plugin. | | jellyfin_discover_tuners | MEDIA_CLIENTTOOL | Discover tuners. | | jellyfin_discvover_tuners | MEDIA_CLIENTTOOL | Discover tuners. | | jellyfin_display_content | MEDIA_CLIENTTOOL | Instructs a session to browse to an item or view. | | jellyfin_download_remote_image | LIBRARY_CLIENTTOOL | Downloads a remote image for an item. | | jellyfin_download_remote_lyrics | MEDIA_CLIENTTOOL | Downloads a remote lyric. | | jellyfin_download_remote_subtitles | MEDIA_CLIENTTOOL | Downloads a remote subtitle. | | jellyfin_enable_plugin | SYSTEM_CLIENTTOOL | Enables a disabled plugin. | | jellyfin_forgot_password | USER_CLIENTTOOL | Initiates the forgot password process for a local user. | | jellyfin_forgot_password_pin | USER_CLIENTTOOL | Redeems a forgot password pin. | | jellyfin_get_additional_part | MEDIA_CLIENTTOOL | Gets additional parts for a video. | | jellyfin_get_album_artists | MEDIA_CLIENTTOOL | Gets all album artists from a given item, folder, or the entire library. | | jellyfin_get_all_channel_features | MEDIA_CLIENTTOOL | Get all channel features. | | jellyfin_get_ancestors | LIBRARY_CLIENTTOOL | Gets all parents of an item. | | jellyfin_get_artist_by_name | MEDIA_CLIENTTOOL | Gets an artist by name. | | jellyfin_get_artist_image | MEDIA_CLIENTTOOL | Get artist image by name. | | jellyfin_get_artists | MEDIA_CLIENTTOOL | Gets all artists from a given item, folder, or the entire library. | | jellyfin_get_attachment | MEDIA_CLIENTTOOL | Get video attachment. | | jellyfin_get_audio_stream | MEDIA_CLIENTTOOL | Gets an audio stream. | | jellyfin_get_audio_stream_by_container | MEDIA_CLIENTTOOL | Gets an audio stream. | | jellyfin_get_auth_providers | USER_CLIENTTOOL | Get all auth providers. | | jellyfin_get_backup | SYSTEM_CLIENTTOOL | Gets the descriptor from an existing archive is present. | | jellyfin_get_bitrate_test_bytes | LIBRARY_CLIENTTOOL | Tests the network with a request with the size of the bitrate. | | jellyfin_get_book_remote_search_results | LIBRARY_CLIENTTOOL | Get book remote search. | | jellyfin_get_box_set_remote_search_results | LIBRARY_CLIENTTOOL | Get box set remote search. | | jellyfin_get_branding_css | SYSTEM_CLIENTTOOL | Gets branding css. | | jellyfin_get_branding_css_2 | SYSTEM_CLIENTTOOL | Gets branding css. | | jellyfin_get_branding_options | SYSTEM_CLIENTTOOL | Gets branding configuration. | | jellyfin_get_channel | MEDIA_CLIENTTOOL | Gets a live tv channel. | | jellyfin_get_channel_features | MEDIA_CLIENTTOOL | Get channel features. | | jellyfin_get_channel_items | MEDIA_CLIENTTOOL | Get channel items. | | jellyfin_get_channel_mapping_options | SYSTEM_CLIENTTOOL | Get channel mapping options. | | jellyfin_get_channels | MEDIA_CLIENTTOOL | Gets available channels. | | jellyfin_get_configuration | SYSTEM_CLIENTTOOL | Gets application configuration. | | jellyfin_get_configuration_pages | SYSTEM_CLIENTTOOL | Gets the configuration pages. | | jellyfin_get_countries | LIBRARY_CLIENTTOOL | Gets known countries. | | jellyfin_get_critic_reviews | LIBRARY_CLIENTTOOL | Gets critic review for an item. | | jellyfin_get_cultures | LIBRARY_CLIENTTOOL | Gets known cultures. | | jellyfin_get_current_user | USER_CLIENTTOOL | Gets the user based on auth token. | | jellyfin_get_dashboard_configuration_page | SYSTEM_CLIENTTOOL | Gets a dashboard configuration page. | | jellyfin_get_default_directory_browser | SYSTEM_CLIENTTOOL | Get Default directory browser. | | jellyfin_get_default_listing_provider | MEDIA_CLIENTTOOL | Gets default listings provider info. | | jellyfin_get_default_metadata_options | SYSTEM_CLIENTTOOL | Gets a default MetadataOptions object. | | jellyfin_get_default_timer | MEDIA_CLIENTTOOL | Gets the default values for a new timer. | | jellyfin_get_device_info | USER_CLIENTTOOL | Get info for a device. | | jellyfin_get_device_options | USER_CLIENTTOOL | Get options for a device. | | jellyfin_get_devices | USER_CLIENTTOOL | Get Devices. | | jellyfin_get_directory_contents | SYSTEM_CLIENTTOOL | Gets the contents of a given directory in the file system. | | jellyfin_get_display_preferences | MEDIA_CLIENTTOOL | Get Display Preferences. | | jellyfin_get_download | LIBRARY_CLIENTTOOL | Downloads item media. | | jellyfin_get_drives | SYSTEM_CLIENTTOOL | Gets available drives from the server's file system. | | jellyfin_get_endpoint_info | SYSTEM_CLIENTTOOL | Gets information about the request endpoint. | | jellyfin_get_episodes | LIBRARY_CLIENTTOOL | Gets episodes for a tv season. | | jellyfin_get_external_id_infos | LIBRARY_CLIENTTOOL | Get the item's external id info. | | jellyfin_get_fallback_font | LIBRARY_CLIENTTOOL | Gets a fallback font file. | | jellyfin_get_fallback_font_list | LIBRARY_CLIENTTOOL | Gets a list of available fallback font files. | | jellyfin_get_file | LIBRARY_CLIENTTOOL | Get the original file of an item. | | jellyfin_get_first_user | USER_CLIENTTOOL | Gets the first user. | | jellyfin_get_first_user_2 | USER_CLIENTTOOL | Gets the first user. | | jellyfin_get_genre | LIBRARY_CLIENTTOOL | Gets a genre, by name. | | jellyfin_get_genre_image | LIBRARY_CLIENTTOOL | Get genre image by name. | | jellyfin_get_genre_image_by_index | LIBRARY_CLIENTTOOL | Get genre image by name. | | jellyfin_get_genres | LIBRARY_CLIENTTOOL | Gets all genres from a given item, folder, or the entire library. | | jellyfin_get_grouping_options | SYSTEM_CLIENTTOOL | Get user view grouping options. | | jellyfin_get_guide_info | MEDIA_CLIENTTOOL | Get guide info. | | jellyfin_get_hls_audio_segment | MEDIA_CLIENTTOOL | Gets a video stream using HTTP live streaming. | | jellyfin_get_hls_audio_segment_legacy_aac | MEDIA_CLIENTTOOL | Gets the specified audio segment for an audio item. | | jellyfin_get_hls_audio_segment_legacy_mp3 | MEDIA_CLIENTTOOL | Gets the specified audio segment for an audio item. | | jellyfin_get_hls_playlist_legacy | MEDIA_CLIENTTOOL | Gets a hls video playlist. | | jellyfin_get_hls_video_segment | MEDIA_CLIENTTOOL | Gets a video stream using HTTP live streaming. | | jellyfin_get_hls_video_segment_legacy | MEDIA_CLIENTTOOL | Gets a hls video segment. | | jellyfin_get_instant_mix_from_album | LIBRARY_CLIENTTOOL | Creates an instant playlist based on a given album. | | jellyfin_get_instant_mix_from_artists | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given artist. | | jellyfin_get_instant_mix_from_artists2 | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given artist. | | jellyfin_get_instant_mix_from_item | LIBRARY_CLIENTTOOL | Creates an instant playlist based on a given item. | | jellyfin_get_instant_mix_from_music_genre_by_id | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given genre. | | jellyfin_get_instant_mix_from_music_genre_by_name | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given genre. | | jellyfin_get_instant_mix_from_playlist | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given playlist. | | jellyfin_get_instant_mix_from_song | MEDIA_CLIENTTOOL | Creates an instant playlist based on a given song. | | jellyfin_get_intros | LIBRARY_CLIENTTOOL | Gets intros to play before the main media item plays. | | jellyfin_get_item | LIBRARY_CLIENTTOOL | Gets an item from a user's library. | | jellyfin_get_item_counts | LIBRARY_CLIENTTOOL | Get item counts. | | jellyfin_get_item_image | LIBRARY_CLIENTTOOL | Gets the item's image. | | jellyfin_get_item_image2 | LIBRARY_CLIENTTOOL | Gets the item's image. | | jellyfin_get_item_image_by_index | LIBRARY_CLIENTTOOL | Gets the item's image. | | jellyfin_get_item_image_infos | LIBRARY_CLIENTTOOL | Get item image infos. | | jellyfin_get_item_segments | MEDIA_CLIENTTOOL | Gets all media segments based on an itemId. | | jellyfin_get_item_user_data | USER_CLIENTTOOL | Get Item User Data. | | jellyfin_get_items | LIBRARY_CLIENTTOOL | Gets items based on a query. | | jellyfin_get_keys | SYSTEM_CLIENTTOOL | Get all keys. | | jellyfin_get_latest_channel_items | MEDIA_CLIENTTOOL | Gets latest channel items. | | jellyfin_get_latest_media | LIBRARY_CLIENTTOOL | Gets latest media. | | jellyfin_get_library_options_info | LIBRARY_CLIENTTOOL | Gets the library options info. | | jellyfin_get_lineups | MEDIA_CLIENTTOOL | Gets available lineups. | | jellyfin_get_live_hls_stream | MEDIA_CLIENTTOOL | Gets a hls live stream. | | jellyfin_get_live_recording_file | MEDIA_CLIENTTOOL | Gets a live tv recording stream. | | jellyfin_get_live_stream_file | MEDIA_CLIENTTOOL | Gets a live tv channel stream. | | jellyfin_get_live_tv_channels | MEDIA_CLIENTTOOL | Gets available live tv channels. | | jellyfin_get_live_tv_info |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Knuckles-Team
• Source: Knuckles-Team/jellyfin-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.