Emby.MCP

Model Context Protocol (MCP) server that connects an Emby media server to an AI client such as Claude Desktop, creating a kind of Amazon Alexa (tm) for any MCP compliant LLM using your own media collection. A personal MCP and Python learning exercise, inspired into action by hearing Yoko Li talk about her Morse Code MCP server.

Note, this is an independent project with no affiliation to, or endorsement by, Emby LLC.

Contents

Features | Requirements | Installation | Usage | Under The Hood | Also See | License

Features

A minimum viable project that allows an LLM to do the following via MCP tools:

• Log on to & log out of an Emby media server;
• Retrieve a list of media libraries;
• Select a specified library;
• Retrieve a list of genres used in that library;
• Search for items in that library by genre, item title, album name, release year, and lyrics, chunking the response as needed;
• Retrieve playlists, create new playlists, add items to playlists & re-order them, and share playlists with other Emby users;
• Retrieve a list of accessible media players known to Emby;
• Retrieve the current play queue of a specified media player;
• Control the playing, pausing, seeking, etc of a specified media player, including transferring the queue to another player.

Requirements

• Python v3.13 or higher
• The uv package/project manager
• The MCP Server SDK for Python v1.94 or higher
• The Emby client SDK for Python v4.9.0.33, with hotfix patches (see below).
• A working Emby Media Server with a library of media files, either local or accessible via a network.
• An MCP-compatible LLM/AI client. Emby.MCP was developed using Claude Desktop, however at time of writing more than 60 other clients were listed in the Feature Support Matrix - pick one that supports Tools.
• An LLM subscription plan that supports MCP (this may require payment).

Installation

The following instructions are for a clean installation on Windows 11 Pro - adjust for your own platform and needs.

Install Python | Install Emby.MCP | Install Patches | Login Config | Basic Checks | Configure LLM

Install Python

• Install latest Python. Customise the install: Optional Features = select all | Advanced Options = install for all, associate files, create shortcuts, add to environment, precompile.
• From a Powershell terminal, run:

pip install uv

• Add uv to the path via Windows Settings > System > About > Advanced > [control panel opens] > Environment Variables > [double-click on Path in the User section at top] > [window opens] > New. Paste in the following (change "313" to the Python version that was installed above, ignoring the 3rd ".x" part): %USERPROFILE%\AppData\Roaming\Python\Python313\Scripts

Install Emby.MCP

• Create empty folder \path\to\Emby.MCP somewhere on your computer.
• Download the Emby.MCP files from GitHub into this folder, overwriting any existing files if you are performing an upgrade.
• Install all dependencies by running the following from a Powershell terminal:

cd "\path\to\Emby.MCP"
uv sync --link-mode=copy

Install Hotfix Patches

At every Python virtual environment sync (like the step above) you will need to patch the Emby client SDK until these fix on github have been incorporated into Emby's official release.

• From a Powershell terminal, run:

cd \path\to\Emby.MCP
copy "hotfixes\emby\configuration.py" ".venv\Lib\site-packages\emby_client"
copy "hotfixes\emby\user_service_api.py" ".venv\Lib\site-packages\emby_client\api"

Login Configuration

The Emby login credentials must be stored in file ".env" which you must create in \path\to\Emby.MCP (for security reasons it is NOT included in the git repo).

• Paste the following into the new ".env" file, amending for your own server as required:

#------------
# Replace with your Emby server login details
EMBY_SERVER_URL = "http://localhost:8096"
EMBY_USERNAME = "user"
EMBY_PASSWORD = "pass"
# Set to False to NOT verify the server's SSL certificate (eg if self-signed). Defaults to True.
EMBY_VERIFY_SSL = True
# Each LLM has an upper limit on the amount of data it can ingest per tool call.
# Set the max number of items returned per chunk by search tools (or 0 for no limit).
# Items with rich metadata can average around 1,800 bytes each in JSON UTF8 format.
LLM_MAX_ITEMS = 100
#------------

• You may want to create a dedicated Emby user for Emby.MCP so that you can limit what it can do and what it can see.

Basic Checks

At this point the script should be able to run some startup checks by accessing your Emby server.

• From a Powershell terminal, run:

cd "\path\to\Emby.MCP"
uv run emby_mcp_server.py

• This should produce an output similar to this (depending on your Emby set up):

Emby.MCP Copyright (C) 2025 Dominic Search <code@angeltek.co.uk>
This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are
welcome to redistribute it under certain conditions; see LICENSE.txt for details.

Running startup checks...
Logon to media server was successful.
Found 3 available libraries
[
  {
    "name": "Music",
    "type": "music",
    "id": "23023"
  },
  {
    "name": "Playlists",
    "type": "playlists",
    "id": "23033"
  },
  {
    "name": "Movies",
    "type": "movies",
    "id": "23042"
  },
]
Logout from media server was successful
Startup checks have completed.

Running Emby.MCP in standalone mode, press CTRL-C to exit.

• If this is successful, press Control-C or close the Powershell terminal to exit the script.

Configure Your LLM MCP Client

• Add the Emby.MCP integration to the MCP SDK by running the following from a Powershell terminal:

cd \path\to\Emby.MCP
uv run mcp install --name "Emby" --with "embyclient" emby_mcp_server.py

• Use the instructions below for your choice of client, If you use a client that is not listed here, then you will need to adapt these instructions yourself.

Claude Desktop

Claude is a good choice as a general-purpose LLM chatbot that works well with Emby.MCP, but requires payment.

• Install the latest Claude Desktop app on the same machine that you installed Python.
• You will need to have at least a Pro subscription - the free plan does not support MCP, unfortunately :-|
• Edit file %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json (Clicking through Claude Desktop > File menu > Settings > Developer > Edit Config will open File Explorer on this file - edit it in Notepad or whatever). Modify so that it looks something like this, noting that on Windows path separators must be escaped as \\ :

{
  "mcpServers": {
    "Emby": {
      "command": "uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\Emby.MCP",
        "--with",
        "embyclient",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "emby_mcp_server.py"
      ]
    }
  }
}

• Ensure Claude Desktop is fully shutdown (File menu > Exit) and then (re)start it.
• Note: if you start Claude Desktop at any time when your Emby server is unavailable then you will get an error message. This is especially the case if Claude is set to "Run on Startup" and your Emby server is installed on the same computer (Claude may start before Emby). Claude will continue to function correctly without Emby.MCP - just restart Claude when the Emby server becomes available.
• If you get an error message on first-time start up for any other reason, double-check the path in claude_desktop_config.json above, especially that it uses \\ not single \ in the directory path.
• Emby.MCP sends messages about serious errors to the standard error output which Claude writes to its log files, so read through %USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Emby.log and %USERPROFILE%\AppData\Roaming\Claude\logs\mcp.log looking for clues. This can be frustrating!

Microsoft Visual Studio Code

Visual Studio Code is a good choice for developers - it integrates with MS Copilot and works reasonably well with Emby.MCP

• Install the latest VS Code app on the same machine that you installed Python. You need at least v1.102 for full MCP support.
• You will need to have a Copilot enabled github account, along with the relevant VS Code extentions installed & working. You do not need a pay-for Copilot Pro subscription - the free plan supports MCP, however you may run into monthly usage limits.
• Use the official documentation to Add an MCP Server, perhaps via your user configuration
• Modify the mcp.json file so that it looks something like this, noting that on Windows path separators must be escaped as \\ :

{
	"servers": {
		"Emby": {
			"command": "uv.exe",
			"args": [
				"run",
				"--directory",
				"C:\\path\\to\\Emby.MCP",
				"--with",
				"embyclient",
				"--with",
				"mcp[cli]",
				"mcp",
				"run",
				"emby_mcp_server.py"
			]
		}
	}
}

• Start and use the Emby.MCP server per the offcial VS Code documentation.

Usage

Allow The Client to Use Tools

The first time an MCP client like Claude Desktop or VS Code tries to use a new MCP tool, a pop-up will appear asking for permission to use it. To avoid being asked each time, press or select Allow always.

Starting a Conversation:

It's a good idea to select an Emby library at the start of a conversation in order to narrow search results and reduce the amount of return data that the LLM has to deal with (that said, you can search across multiple libraries if you wish). E.g., from Claude:

list emby libraries

I'll help you explore your Emby library. Let me start by checking what libraries are available on your Emby server.

Your Emby server has several libraries available:

• Music - Main music library

• Playlists - Your saved playlists

• Movies - Movie collection

• BBC Sounds - BBC audio content

select bbc library

Perfect! I've selected the BBC Sounds library.

You can now search, browse, or explore content within the BBC Sounds library. What would you like to do next?

Instructing Your LLM

On startup, the MCP client receives the list of tools from Emby.MCP (all functions that have @mcp.tool() immediately prior to their def line), along with the parameter names and the content of the docstring.

The docstring is a natural language description of the tool, its parameters and its output. From this, the LLM gains an understanding of the capabilities it has at hand, and is quite good at reasoning which tools are required for the instructions that you give it. But it isn't perfect, so:

• Be brief and specific to reduce LLM confusion.
• Start a conversation by mentioning Emby as a hint that Emby.MCP tools should be used.
• If you want to search