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 · Transport · Options · MCP capabilities · 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 for the full list.

Setup

1. Get a Jellyfin API key

1. Open your Jellyfin web UI
2. Go to Administration > Dashboard > 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) |

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.

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
2. Add the following:

If you installed the binary:

{
  "mcpServers": {
    "jellyfin": {
      "command": "jellyfin-mcp",
      "env": {
        "JELLYFIN_URL": "https://jellyfin_host:8920",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

If Claude can't find the binary, replace "jellyfin-mcp" with the full path (run which jellyfin-mcp on macOS/Linux or where jellyfin-mcp on Windows to find it).

Or skip the install — run directly with Go:

{
  "mcpServers": {
    "jellyfin": {
      "command": "go",
      "args": ["run", "github.com/jaredtrent/jellyfin-mcp@latest"],
      "env": {
        "JELLYFIN_URL": "https://jellyfin_host:8920",
        "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=https://jellyfin_host:8920 \
  -e JELLYFIN_API_KEY=your_api_key \
  jellyfin -- jellyfin-mcp

# Or run directly with Go:
claude mcp add \
  -e JELLYFIN_URL=https://jellyfin_host:8920 \
  -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):

{
  "mcp": {
    "jellyfin": {
      "type": "local",
      "command": ["jellyfin-mcp"],
      // Or run directly with Go:
      // "command": ["go", "run", "github.com/jaredtrent/jellyfin-mcp@latest"],
      "environment": {
        "JELLYFIN_URL": "https://jellyfin_host:8920",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

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": "https://jellyfin_host:8920",
        "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": "https://jellyfin_host:8920",
        "JELLYFIN_API_KEY": "your_api_key"
      }
    }
  }
}

Alternatively, connect via HTTP transport:

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

JELLYFIN_URL=https://jellyfin_host:8920 \
JELLYFIN_API_KEY=your_api_key \
jellyfin-mcp -http -http-token your_secret_token

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

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 (default: https://jellyfin_host:8920) | | 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 for the full list with descriptions.

Access control examples

# Casual use — search, browse, and play only (13 read-only + playback tools)
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 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 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+ and 10.9+. 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