Skip to main content
Glama
mardelplatadev

Jellyfin MCP Server

by mardelplatadev
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

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

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.