Skip to content

Usage — MCP / API / Agent

jellyfin-mcp exposes the same capability three ways: as MCP tools an agent calls, as a Python API (Api) the operator import, and as an A2A agent CLI. The agent-package pattern and MCP configuration are covered in Overview.

As an MCP server

Once deployed, the server registers one typed tool per Jellyfin API operation, named jellyfin_<operation> (for example jellyfin_get_items, jellyfin_get_system_info, jellyfin_create_playlist). Arguments are typed tool parameters; there is no action router and no params_json string. A fleet gateway loads them on demand.

Example agent prompts that map onto these tools:

  • "List the movies in my library" -> jellyfin_get_items with include_item_types=["Movie"]
  • "Search the library for items named like 'matrix'" -> jellyfin_get_search_hints
  • "Show the Jellyfin server's system information" -> jellyfin_get_system_info

As a Python API

Api is a unified client composed of modular media, library, system, and user sub-clients. Build one directly, or from the environment with get_client().

from jellyfin_mcp.api_client import Api

api = Api(
    base_url="http://your-jellyfin:8096",
    token="your_api_key",
)

# Reads
info = api.get_system_info()  # server name, version, OS
movies = api.get_movies()  # movie library items
results = api.search_items(searchTerm="matrix")
views = api.get_user_views()  # the caller's library views

TLS verification is always enabled. Configure private trust chains, mTLS, and proxy policy with JELLYFIN_TLS_PROFILE or JELLYFIN_TLS_PROFILE_REF; direct clients resolve the active AgentConfig profile automatically.

Build a client straight from the environment:

from jellyfin_mcp.auth import get_client

api = get_client()  # reads JELLYFIN_* from the environment / .env
users = api.get_users()

get_client() selects the authentication flow automatically: a JELLYFIN_API_KEY when present, otherwise JELLYFIN_USERNAME + JELLYFIN_PASSWORD, or an OIDC token-exchange delegation when ENABLE_DELEGATION=true. When no credentials are configured it raises a clear error rather than connecting anonymously.

As an A2A agent

The integrated Pydantic-AI graph agent is published as the jellyfin-agent console script. It connects to the MCP server, routes each query to a focused domain, and serves an optional Web UI.

export JELLYFIN_URL=http://your-jellyfin:8096
export JELLYFIN_API_KEY=your_api_key

jellyfin-agent --provider openai --model-id gpt-4o --host 0.0.0.0 --port 9056

Point the agent at an already-running MCP server with --mcp-url (http://jellyfin-mcp-mcp:8000/mcp), or let it auto-discover servers from mcp_config.json. See Deployment for the combined Docker Compose stack.