Jellyfin MCP Server

An MCP server that lets AI assistants manage a Jellyfin media server. Built with FastMCP and designed for use with Claude Code, but compatible with any MCP client.

Capabilities

Library Management

• List libraries — enumerate all configured libraries (Movies, Music, Shows, Books, etc.)

• Scan libraries — trigger a full rescan or rescan a specific library

Search & Browse

• Search media — find items by keyword with optional type filtering (Audio, MusicAlbum, MusicArtist, Movie, Series, Episode, Book)

• Browse library — paginated browsing with configurable sorting (by name, date added, rating, year, etc.)

• Get item details — full metadata for any item including genres, tags, people, file path, bitrate, and provider IDs

• Get recent items — recently added content, sorted newest first

• Find similar items — discover related content based on a given item

Playlist Management

• List, create, and delete playlists

• Modify playlists — add and remove items in a single operation

• Inspect playlist contents — includes playlist-item IDs needed for removal

Scheduled Tasks

• List scheduled tasks — see all tasks with their current state and progress percentage

• Run tasks on demand — trigger any scheduled task immediately (library scans, lyrics downloads, etc.)

Server Monitoring

• Server status — version info, active sessions (with now-playing), scheduled task states, and recent activity log — all in a single configurable call

Related MCP server: Plex Assistant MCP

Requirements

• Python 3.10+

• uv (recommended) or pip

• A Jellyfin server with an API key

Installation

git clone https://github.com/AlphaGit/jellyfin-mcp-server.git
cd jellyfin-mcp-server
uv sync

Configuration

1. Generate an API key in the Jellyfin dashboard under Administration > Advanced > API Keys

2. Copy the example env file and fill in your values:

cp .env.example .env

JELLYFIN_URL=https://your-jellyfin-server.com
JELLYFIN_API_KEY=your-api-key-here
JELLYFIN_USERNAME=your-username-here

The username is resolved to a user ID at startup. This is required for user-scoped API calls (playlists, item details, etc.) since API key authentication doesn't support the /Users/Me endpoint.

Usage with Claude Code

The repository includes a .mcp.json that registers the server automatically. Just open Claude Code in the project directory and restart — the tools will be available immediately.

To use this server from a different project, add it to that project's .mcp.json:

{
  "mcpServers": {
    "jellyfin": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "/path/to/jellyfin-mcp-server", "python", "jellyfin_mcp.py"]
    }
  }
}

Usage with other MCP clients

Run the server directly:

uv run python jellyfin_mcp.py

The server communicates over stdio using the MCP protocol.

License

MIT

Origin

This repository was copied from AlphaGit/jellyfin-mcp-server.