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