Jellyfin Mcp

CLI or API | MCP

Version: 2.3.0

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
• Key Features
• Installation
• Quick Start
• CLI or API
• MCP Integration
  • Available MCP Tools
  • MCP Configuration Examples
• Agent Capabilities
  • Running the Agent CLI
  • Docker Compose Orchestration
• Security & Governance
• Documentation
• 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 the operator's connection keys and Jellyfin host details (see .env.example for complete list):

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

3. Run the MCP Server

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

jellyfin-mcp

4. Run the Agent CLI

To start 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: Complete 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. The operator 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.

---

MCP

This server use 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.

<!-- MCP-TOOLS-TABLE:START -->

Condensed action-routed tools (MCP_TOOL_MODE=condensed)

| MCP Tool | Toggle Env Var | Description | |----------|----------------|-------------| | jellyfin_ingest_library | KG_INGESTTOOL | Natively ingest the Jellyfin library into epistemic-graph as typed nodes. | | jellyfin_ingest_posters | KG_INGESTTOOL | Ingest item posters as content-addressed :Blob + :AssetOccurrence (best-effort). | | 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)

<details> <summary>368 per-operation tools — one per public API method (click to expand)</summary>

| 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 |