Knuckles-Team/jellyfin-mcp

## CLI or API | MCP
> 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:
bash
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):
bash
export JELLYFINURL="http://localhost:8096"
export JELLYFINAPIKEY="yourapikeyhere"
### 3. Run the MCP Server
Start the server over standard standard I/O (stdio) transport:
bash
jellyfin-mcp
### 4. Run the Agent CLI
To start the interactive Graph Agent terminal interface:
bash
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.
#### Condensed action-routed tools (MCPTOOLMODE=condensed)
| MCP Tool | Toggle Env Var | Description |
| jellyfiningestlibrary | KGINGESTTOOL | Natively ingest the Jellyfin library into epistemic-graph as typed nodes. |
| jellyfiningestposters | KGINGESTTOOL | Ingest item posters as content-addressed :Blob + :AssetOccurrence (best-effort). |
| jellyfinlibrary | CONDENSEDJELLYFINTOOL | Execute library searches, items, collection updates, and catalog queries dynamically. |
| jellyfinmedia | CONDENSEDJELLYFINTOOL | Execute media playback, stream, artist, playlist, and audio/video queries dynamically. |
| jellyfinsystem | CONDENSEDJELLYFINTOOL | Execute administrative actions, system status, configurations, backups, and user management. |
#### Verbose 1:1 API-mapped tools (MCPTOOLMODE=verbose or both)
368 per-operation tools — one per public API method (click to expand)
| MCP Tool | Toggle Env Var | Description |