Jellyfin Mcp

jellyfin-mcp

[](https://github.com/jaredtrent/jellyfin-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://go.dev) [](https://www.npmjs.com/package/@jaredtrent/jellyfin-mcp)

MCP server that connects AI assistants to your Jellyfin media server — 31 tools, 13 live resources, and 18 guided workflows. Search your library, control playback, manage metadata, find subtitles, troubleshoot your server, and more.

[Setup](#setup) · [Transport](#transport) · [Options](#options) · [MCP capabilities](#mcp-capabilities) · [Important notes](#important-notes)

What can it do?

• Find and play media — search your library and start playback on any connected client
• Browse and filter — by genre, year, studio, actor, rating, played status, and more
• Recommendations — personalized suggestions from your own library, not external sites
• Control playback — play, pause, seek, stop, volume, next/previous on any device
• Playlists and collections — create, manage, deduplicate playlists and box set collections
• Music — browse artists, albums, genres; generate instant mix playlists
• Subtitles — search, download, and audit missing subtitles across your library
• Metadata management — fix titles, genres, ratings, images; batch updates; re-identify items
• Troubleshoot your server — read server logs, check failed tasks, diagnose playback issues
• Server admin — user management, library scans, scheduled tasks, plugins, devices, backups
• Analytics — watch history, codec reports, duplicate detection, library stats
• Live TV and DVR — guide data, channels, recordings, series timers
• SyncPlay — synchronized group watching sessions

Built-in knowledge

Includes 10 reference guides the AI can consult to help with Jellyfin setup and troubleshooting — transcoding, Docker, file naming, remote access, migrating from Plex/Emby, performance tuning, and more.

Safety controls

• Read-only mode — prevent all writes with --read-only
• Disable destructive operations — block deletes, restarts, and shutdowns with --disable-destructive
• Toolset scoping — expose only the tool groups you need with --toolsets
• Confirmation required — destructive operations require explicit confirm=true; the AI is instructed to ask the user before any write operation
• HTTP authentication — bearer token auth for HTTP transport

Prompts

18 pre-built workflows like movie-night, binge-watch, library-health, troubleshoot, duplicate-finder, and codec-optimize that guide the AI through multi-step tasks. See [prompts](internal/server/prompts) for the full list.

Setup

1. Get a Jellyfin API key

1. Open your Jellyfin web UI
2. Go to Dashboard > Advanced > API Keys
3. Click + to create a new key
4. Give it a name (e.g., "MCP") and copy the key

2. Install jellyfin-mcp

| Method | Command | Requirements | |--------|---------|--------------| | Binary | Download from Releases | None | | Go install | go install github.com/jaredtrent/jellyfin-mcp@latest | Go 1.25+ | | Go run | go run github.com/jaredtrent/jellyfin-mcp@latest | Go 1.25+ | | npx | npx -y @jaredtrent/jellyfin-mcp | npm (linux/x64 only) | | Docker | docker pull ghcr.io/jaredtrent/jellyfin-mcp | Docker |

Detailed instructions for each method

Binary — download and extract:

1. Download the archive for your platform from Releases
2. Extract it: tar xzf jellyfin-mcp_*.tar.gz (or unzip on Windows)
3. Move the binary somewhere on your PATH: sudo mv jellyfin-mcp /usr/local/bin/
4. Verify: jellyfin-mcp --help

Go install — places the binary in $GOPATH/bin (usually ~/go/bin). Make sure that directory is on your PATH, then verify: jellyfin-mcp --help. (GUI clients may not see ~/go/bin — see the Claude Desktop note below.)

Go run — no install step, best for a quick try. go run …@latest re-resolves the latest version and rebuilds on each launch, adding startup latency that can make MCP clients time out; go must also be on the client's PATH. Install the binary for regular use.

npx — bundles a pre-compiled linux/x64 binary. Intended for MetaMCP and other Docker-based MCP gateways. For other platforms, use one of the methods above.

Docker — a multi-arch image (linux/amd64, linux/arm64) published to GHCR. Runs the Streamable HTTP transport by default. See the [Docker](#docker) section below.

3. Connect to your MCP client

Pick the client you use and follow the steps below. In every example, replace the URL and API key with yours — use http://YOUR_SERVER:8096 for a standard install, or https://YOUR_SERVER:8920 only if you've enabled HTTPS in Jellyfin.

Claude Desktop

1. Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

1. Add the following:

If you installed the binary:

{
  "mcpServers": {
    "jellyfin": {
      "command": "jellyfin-mcp",
      "env": {
        "JELLYFIN_URL": "http://YOUR_SERVER:8096",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

If Claude can't find the binary, use its full path instead of "jellyfin-mcp" — GUI apps don't inherit your shell PATH, so a go install binary in ~/go/bin is often invisible to them. Run which jellyfin-mcp (macOS/Linux) or where jellyfin-mcp (Windows) to get the path.

Or skip the install — run directly with Go (recompiles each launch — slower startup, best for a quick try):

{
  "mcpServers": {
    "jellyfin": {
      "command": "go",
      "args": ["run", "github.com/jaredtrent/jellyfin-mcp@latest"],
      "env": {
        "JELLYFIN_URL": "http://YOUR_SERVER:8096",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Claude Desktop for the changes to take effect.

Claude Code

# If installed:
claude mcp add \
  -e JELLYFIN_URL=http://YOUR_SERVER:8096 \
  -e JELLYFIN_API_KEY=your_api_key \
  jellyfin -- jellyfin-mcp

# Or run directly with Go:
claude mcp add \
  -e JELLYFIN_URL=http://YOUR_SERVER:8096 \
  -e JELLYFIN_API_KEY=your_api_key \
  jellyfin -- go run github.com/jaredtrent/jellyfin-mcp@latest

OpenCode

Add to ~/.config/opencode/opencode.json (or opencode.json in your project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jellyfin": {
      "type": "local",
      "command": ["jellyfin-mcp"],
      "enabled": true,
      "environment": {
        "JELLYFIN_URL": "http://YOUR_SERVER:8096",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

To run with Go instead of an installed binary, set "command": ["go", "run", "github.com/jaredtrent/jellyfin-mcp@latest"].

MetaMCP

MetaMCP runs in Docker with npx pre-installed. Use the npm package to run via stdio (no HTTP setup needed):

{
  "mcpServers": {
    "jellyfin": {
      "command": "npx",
      "args": ["-y", "@jaredtrent/jellyfin-mcp"],
      "env": {
        "JELLYFIN_URL": "http://YOUR_SERVER:8096",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

With CLI flags:

{
  "mcpServers": {
    "jellyfin": {
      "command": "npx",
      "args": ["-y", "@jaredtrent/jellyfin-mcp", "--read-only", "--toolsets", "discovery,media,playback"],
      "env": {
        "JELLYFIN_URL": "http://YOUR_SERVER:8096",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

Alternatively, connect via HTTP transport:

1. Run jellyfin-mcp in HTTP mode on your host:

JELLYFIN_URL=http://YOUR_SERVER:8096 \
JELLYFIN_API_KEY=your_api_key \
jellyfin-mcp --http --http-token your_secret_token

1. In the MetaMCP dashboard, add a new Streamable HTTP server:

• URL: http://host.docker.internal:8080/mcp
• Bearer Token: your_secret_token

host.docker.internal reaches the host from inside Docker (macOS/Windows). On Linux, add --addr 0.0.0.0:8080 and use your host's LAN IP instead of host.docker.internal.

Transport

jellyfin-mcp supports two transport modes. Use whichever your MCP client requires.

| Transport | Flag | When to use | |-----------|------|-------------| | stdio | (default) | Claude Desktop, Claude Code, and most MCP clients that launch a local process | | Streamable HTTP | --http | MetaMCP (HTTP mode), or any client that connects to a remote URL |

stdio — the server communicates over stdin/stdout. The MCP client starts jellyfin-mcp as a subprocess and manages its lifecycle. This is the simplest setup and works with most clients.

Streamable HTTP — the server listens on an HTTP endpoint (/mcp) that supports bidirectional streaming. Use this when your MCP client can't run a local process or when you want to run the server on a different machine from the client.

# Start in HTTP mode on localhost
jellyfin-mcp --http

# Listen on all interfaces with auth (required for non-localhost)
jellyfin-mcp --http --addr 0.0.0.0:8080 --http-token your_secret_token

The HTTP server also exposes /health (returns {"status":"ok"}) for monitoring and load balancer health checks. Sessions time out after 30 minutes of inactivity.

Docker

A multi-arch image (linux/amd64, linux/arm64) is published to the GitHub Container Registry: ghcr.io/jaredtrent/jellyfin-mcp. It runs the Streamable HTTP transport by default, serving the MCP endpoint at /mcp and a health check at /health.

docker run -d --name jellyfin-mcp -p 8080:8080 \
  -e JELLYFIN_URL=http://YOUR_SERVER:8096 \
  -e JELLYFIN_API_KEY=your_api_key \
  ghcr.io/jaredtrent/jellyfin-mcp --http --addr 0.0.0.0:8080 --http-token your_secret_token

A bearer token is required when binding a non-localhost address, so always pass --http-token. Point your MCP client at http://:8080/mcp and send Authorization: Bearer your_secret_token.

docker compose — a ready-to-edit [docker-compose.yml](docker-compose.yml) is included. Set your Jellyfin URL/key and token, then docker compose up -d.

stdio in Docker — for clients that launch the server as a subprocess, override the entrypoint so it runs with no arguments:

docker run -i --rm \
  -e JELLYFIN_URL=http://YOUR_SERVER:8096 \
  -e JELLYFIN_API_KEY=your_api_key \
  --entrypoint /usr/local/bin/jellyfin-mcp \
  ghcr.io/jaredtrent/jellyfin-mcp

Image tags: latest (latest build from main), the full version from release tags (e.g. 2026.603.1), and MAJOR.MINOR.

Options

Flags

| Flag | Description | Default | |------|-------------|---------| | --toolsets | Comma-separated toolset groups to enable | all | | --read-only | Only register read-only tools — no writes, deletes, or mutations | off | | --disable-destructive | Skip destructive tools (delete, restart, shutdown) while allowing other writes | off | | --http | Run as Streamable HTTP server instead of stdio | off | | --addr | HTTP listen address | 127.0.0.1:8080 | | --http-token | Bearer token for HTTP authentication (required when listening on non-localhost) | none |

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | JELLYFIN_API_KEY | Yes | API key from your Jellyfin dashboard | | JELLYFIN_URL | No | Server URL — e.g. http://YOUR_SERVER:8096, or https://YOUR_SERVER:8920 if HTTPS is enabled. Defaults to a placeholder, so set this. | | JELLYFIN_USER_ID | No | User ID — auto-detected from the API key if not set |

Toolsets

31 tools organized into 8 groups. Enable specific groups with --toolsets discovery,media,... to reduce context size and keep the AI focused. By default, all toolsets are enabled.

| Toolset | Tools | Covers | |---------|-------|--------| | discovery | 6 | Search, browse, recommendations, item details | | media | 3 | TV shows, music, people | | user | 3 | Favorites, playlists, collections | | playback | 4 | Sessions, playback control, SyncPlay | | admin | 8 | System, users, libraries, tasks, plugins, devices, server config | | content | 4 | Metadata, subtitles, images, video versions | | livetv | 2 | Channels, guide, recordings, DVR | | analytics | 1 | Stats, codec reports, duplicates |

For a casual "search and play" setup, --toolsets discovery,media,playback is a good starting point. Add user for playlist/collection management or admin for server maintenance. See [tools](internal/server/tools) for the full list with descriptions.

Access control examples

# Casual use — search, browse, and play only (13 tools: read-only discovery/media + playback)
jellyfin-mcp --toolsets discovery,media,playback

# Shared family server — allow playlists and favorites, block all admin operations
jellyfin-mcp --toolsets discovery,media,user,playback

# Full access, but protect against accidental deletes/restarts
jellyfin-mcp --disable-destructive

# Monitoring/analytics only — no writes at all
jellyfin-mcp --read-only --toolsets discovery,analytics

MCP capabilities

Beyond tools, jellyfin-mcp implements several MCP protocol features that compatible clients can use.

Resources — 13 live data endpoints the AI can read without a tool call. These include server info, library lists, active sessions, now-playing, favorites, recently played, and more. Clients that support MCP resources can access these directly for quick lookups. See [resources](internal/server/resources) for the full list.

Resource subscriptions — Clients can subscribe to session and content resources for real-time change notifications. Sessions are polled every 10 seconds; content (latest additions, recently played) every 60 seconds. The server only polls when at least one subscription is active.

Prompts — 18 pre-built workflows the AI can invoke for multi-step tasks. See [prompts](internal/server/prompts) for the full list.

Completions — Prompt arguments and resource template URIs support auto-completion (e.g., genre lists, language codes, item/user/library ID lookups).

Logging — Tool calls emit structured MCP log notifications with timing data back to the client, in addition to stderr logging for local debugging.

Important notes

API key permissions — The API key grants full access to whatever Jellyfin permissions are available. For shared or less trusted setups, pair it with --read-only or --toolsets to limit what the AI can do.

Network exposure — In stdio mode, the server is only accessible to the local MCP client process. In HTTP mode, use --http-token whenever the server is reachable beyond localhost. The server refuses to start on a non-localhost address without a token.

Jellyfin version — Tested against Jellyfin 10.8 through 10.11. Older versions may be missing some API endpoints (e.g., playback reporting, activity log queries).

Single binary, no runtime dependencies — jellyfin-mcp is a statically compiled Go binary. No Node.js, Python, Java, or container runtime is required. The npm package is just a delivery wrapper around the same binary.

License

[MIT](LICENSE)

AI Disclosure

This project was made with the help of AI tools, but with a lot of manual effort towards SDK compliance, usability, and minimal slop.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jaredtrent
• Source: jaredtrent/jellyfin-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.