Skip to content

jellyfin-mcp

Jellyfin media-server API + MCP Server + A2A Agent for the agent-utilities ecosystem — a typed, deterministic tool surface over the Jellyfin REST API for agentic media management.

Official documentation

This site is the canonical reference for jellyfin-mcp, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

jellyfin-mcp wraps the Jellyfin media server's REST surface with consolidated, action-routed MCP tools, and ships an integrated Pydantic-AI graph agent. It provides:

  • Api — a unified Python client composed of modular media, library, system, and user sub-clients over the Jellyfin REST API.
  • Condensed, action-routed MCP tools — jellyfin_media, jellyfin_library, and jellyfin_system dispatch dynamically to the client methods, minimizing tool bloat in the LLM context window.
  • An A2A graph agent (jellyfin-agent console script) — a Pydantic-AI agent with a confidence-gated router, optional Web UI (AG-UI), and OpenTelemetry tracing.

Credentials are read from the environment; the server remains inactive when credentials are absent rather than failing at import time.

Explore the documentation

  • Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the MCP and agent servers, Docker Compose, Caddy + Technitium.
  • Usage — the MCP tools, the Api client, and the agent CLI.
  • Backing Platform — deploy a Jellyfin media server with Docker.
  • Architecture — the agent-package pattern and MCP configuration.
  • Concepts — the CONCEPT:JELLYFIN-* registry.

Quick start

pip install jellyfin-mcp
jellyfin-mcp                       # stdio MCP server (default transport)

Connect it to a Jellyfin server:

export JELLYFIN_URL=http://your-jellyfin:8096
export JELLYFIN_API_KEY=your_api_key
jellyfin-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).