Emby.MCP

Model Context Protocol (MCP) 服务器，用于连接Emby媒体服务器与AI客户端（如Claude Desktop），创建一种类似于Amazon Alexa™的工具，适用于任何符合MCP标准的大型语言模型（LLM），并使用您自己的媒体收藏。这是一个个人项目，旨在学习MCP和Python，灵感来源于Yoko Li关于她的Morse Code MCP服务器的演讲。

注意：这是一个独立项目，与Emby LLC无关且未得到其认可。

内容

功能 | 需求 | 安装 | 使用 | 内部工作原理 | 相关链接 | 许可证

功能

一个最小可行项目，允许LLM通过MCP工具执行以下操作：

• 登录和注销Emby媒体服务器；
• 获取媒体库列表；
• 选择指定的库；
• 获取该库中使用的类型列表；
• 按类型、项目标题、专辑名称、发行年份和歌词搜索库中的项目，并根据需要分块返回结果；
• 获取播放列表，创建新播放列表，向播放列表添加项目并重新排序，以及与其他Emby用户共享播放列表；
• 获取Emby已知的所有可访问媒体播放器列表；
• 获取指定媒体播放器的当前播放队列；
• 控制指定媒体播放器的播放、暂停、快进等操作，包括将队列转移到另一个播放器。

需求

• Python v3.13或更高版本
• uv 包/项目管理器
• MCP Server SDK for Python v1.94或更高版本
• Emby客户端SDK for Python v4.9.0.33，附带热修复补丁（见下文）。
• 工作中的Emby Media Server，包含本地或网络可访问的媒体文件库。
• 与MCP兼容的LLM/AI客户端。Emby.MCP使用Claude Desktop进行开发，但撰写本文时，特性支持矩阵中列出了超过60个其他客户端——选择一个支持工具的客户端。
• 支持MCP的LLM订阅计划（这可能需要付费）。

安装

以下说明适用于Windows 11 Pro上的全新安装——请根据您的平台和需求进行调整。

安装Python | 安装Emby.MCP | 安装热修复补丁 | 登录配置 | 基本检查 | 配置LLM

安装Python

• 安装最新版Python。自定义安装：可选功能 = 全部选中 | 高级选项 = 对所有人安装，关联文件，创建快捷方式，添加到环境变量，预编译。
• 在PowerShell终端中运行：

pip install uv

• 通过Windows设置 > 系统 > 关于 > 高级 > [控制面板打开] > 环境变量 > [双击顶部用户部分的Path] > [窗口打开] > 新建。粘贴以下内容（将“313”替换为您上面安装的Python版本，忽略第三位“.x”部分）：%USERPROFILE%\AppData\Roaming\Python\Python3113\Scripts

安装Emby.MCP

• 在计算机上某个位置创建空文件夹 \path\to\Emby.MCP。
• 将从GitHub下载的Emby.MCP文件放入此文件夹中，如果进行升级，则覆盖现有文件。
• 通过在PowerShell终端中运行以下命令来安装所有依赖项：

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

安装热修复补丁

每次Python虚拟环境同步（如上述步骤）时，您都需要修补Emby客户端SDK，直到这些修复被合并到Emby的官方发布中。

• 在PowerShell终端中运行：

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"

登录配置

Emby登录凭据必须存储在文件".env"中，您需要在\path\to\Emby.MCP中创建这个文件（出于安全原因，它不包含在git仓库中）。

• 将以下内容粘贴到新的".env"文件中，并根据您的服务器进行修改：

#------------
# 替换为您的Emby服务器登录详情
EMBY_SERVER_URL = "http://localhost:8096"
EMBY_USERNAME = "user"
EMBY_PASSWORD = "pass"
# 设置为False以不验证服务器的SSL证书（例如自签名证书）。默认为True。
EMBY_VERIFY_SSL = True
# 每个LLM在每次工具调用中可以摄入的数据量都有上限。
# 设置每个搜索工具返回的最大项目数（或0表示无限制）。
# 富含元数据的项目平均每个大约1,800字节（JSON UTF8格式）。
LLM_MAX_ITEMS = 100
#------------

• 您可能希望为Emby.MCP创建一个专用的Emby用户，以便您可以限制它可以做什么和可以看到什么。

基本检查

此时，脚本应该能够通过访问您的Emby服务器来运行一些启动检查。

• 在PowerShell终端中运行：

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

• 这应该产生类似以下输出（取决于您的Emby设置）：

Emby.MCP 版权所有 (C) 2025 Dominic Search <code@angeltek.co.uk>
本程序绝对没有任何保证。这是自由软件，您可以在一定条件下重新分发它；详情请参阅LICENSE.txt。

正在运行启动检查...
登录媒体服务器成功。
找到3个可用库
[
  {
    "name": "音乐",
    "type": "音乐",
    "id": "23023"
  },
  {
    "name": "播放列表",
    "type": "播放列表",
    "id": "23033"
  },
  {
    "name": "电影",
    "type": "电影",
    "id": "23042"
  },
]
从媒体服务器注销成功。
启动检查已完成。

正在以独立模式运行Emby.MCP，按CTRL-C退出。

• 如果成功，请按Control-C或关闭PowerShell终端以退出脚本。

配置您的LLM MCP客户端

• 通过在PowerShell终端中运行以下命令，将Emby.MCP集成添加到MCP SDK：

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

• 根据您选择的客户端使用以下说明。如果您使用的是此处未列出的客户端，则需要自行调整这些说明。

Claude Desktop

Claude是一个很好的通用LLM聊天机器人，与Emby.MCP配合得很好，但需要付费。

• 在您安装Python的同一台机器上安装最新版Claude Desktop应用。
• 您至少需要有一个Pro订阅——免费计划不支持MCP，不幸的是 :-|
• 编辑文件%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json（点击Claude Desktop > 文件菜单 > 设置 > 开发者 > 编辑配置将打开此文件所在的文件资源管理器——使用记事本或其他编辑器编辑它）。修改使其看起来像这样，注意在Windows路径分隔符必须转义为\\：

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

• 确保Claude Desktop完全关闭（文件菜单 > 退出），然后重新启动它。
• 注意：如果您在Emby服务器不可用时启动Claude Desktop，您将收到错误消息。特别是当Claude设置为“开机启动”且Emby服务器安装在同一台计算机上时（Claude可能会在Emby之前启动）。即使没有Emby.MCP，Claude仍能正常工作——只需在Emby服务器可用时重新启动Claude即可。
• 如果您在首次启动时遇到任何其他原因导致的错误消息，请再次检查claude_desktop_config.json中的路径，特别注意目录路径中使用的是\\而不是单个\。
• Emby.MCP会将有关严重错误的消息发送到标准错误输出，而Claude将其写入日志文件，因此请查看%USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Emby.log和%USERPROFILE%\AppData\Roaming\Claude\logs\mcp.log寻找线索。这可能会令人沮丧！

Microsoft Visual Studio Code

Visual Studio Code是开发人员的好选择——它与MS Copilot集成，并且与Emby.MCP配合得相当好。

• 在您安装Python的同一台机器上安装最新版VS Code应用。您需要至少v1.102才能获得完整的MCP支持。
• 您需要一个启用GitHub账户的Copilot，并安装和运行相关的VS Code扩展。您不需要付费的Copilot Pro订阅——免费计划支持MCP，但您可能会遇到每月使用限制。
• 使用官方文档添加一个MCP服务器，也许通过您的用户配置
• 修改mcp.json文件，使其看起来像这样，注意在Windows路径分隔符必须转义为\\：

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

• 按照官方VS Code文档开始并使用Emby.MCP服务器。

使用

允许客户端使用工具

当MCP客户端（如Claude Desktop或VS Code）第一次尝试使用新的MCP工具时，会出现一个弹出窗口询问是否允许使用它。为了避免每次都被询问，选择始终允许。

启动对话：

在对话开始时选择一个Emby库是个好主意，以便缩小搜索结果范围并减少LLM需要处理的返回数据量（尽管如此，如果您愿意，也可以跨多个库进行搜索）。例如，从Claude：

列出Emby库

我可以帮助您探索您的Emby库。让我先检查一下您的Emby服务器上有哪些可用的库。

您的Emby服务器有以下几个可用库：

• 音乐 - 主音乐库

• 播放列表 - 您保存的播放列表

• 电影 - 电影收藏

• BBC Sounds - BBC音频内容

选择BBC库

很好！我已经选择了BBC Sounds库。

您现在可以搜索、浏览或探索BBC Sounds库中的内容。接下来您想做什么？

指导您的LLM

在启动时，MCP客户端接收来自Emby.MCP的工具列表（所有函数在其def行前都有@mcp.tool()），以及参数名称和docstring的内容。

Docstring是对工具及其参数和输出的自然语言描述。从这一点出发，LLM获得了对其手头能力的理解，并且在推理哪些工具适合您给它的指令方面相当擅长。但它并不完美，所以：

• 简洁具体以减少LLM的困惑。
• 在对话开始时提到Emby作为提示，表明应使用Emby.MCP工具。
• 如果您想基于歌词或描述中的短语搜索音频或视频，请在您的指令中明确指出这一点，否则LLM可能只会搜索标题或艺术家。
• LLM试图避免摄入大量数据，例如从大型库中模糊搜索。Emby.MCP通过返回分块的结果来解决这个问题。有时即使这样也不够，因此您的指令可能需要创造性地说服。

示例对话

我的Emby服务器包含许多BBC广播音频剧集文件，这些文件具有丰富的mp3/mp4元数据，包括歌词字段中的长描述和完整的演员名单。这对于演示Emby.MCP来说是很好的材料……请参阅单独的文件示例Claude对话.md

内部工作原理

Emby.MCP代码分布在三个文件中。emby_mcp_server.py包含所有与MCP相关的工具函数。在正常使用中，MCP不需要有一个经典的“主”函数来调用（尽管这里用于测试目的）。相反，MCP服务器SDK解析声明为@mcp.tool()的函数，并将这些函数提供给MCP客户端直接调用。

在客户端启动时，会执行一些初步操作，其中包括实例化FastMCP和带有“生命周期”函数app_lifespan。这是一个异步代码，登录Emby服务器，初始化一些可更新的“上下文”存储（类似于全局变量），然后等待客户端退出（导致app_lifespan注销Emby）或由其他函数触发以释放其存储（工具函数可以读写上下文存储）。

MCP工具函数主要是对lib_emby_functions.py中进行繁重工作的函数的薄包装。这些包装器是为LLM理解而写的，因此函数、参数和docstring的名字较长（记住，MCP SDK将所有这些传递给LLM，以便它获得对工具的详细理解）。它们只返回字符串——要么是成功/错误消息，要么是JSON格式的数据。

例外是search_for_item()和retrieve_next_search_chunk()，它们试图通过将返回结果分块为小块（由.env文件中的LLM_MAX_ITEMS变量定义）来引导LLM接受更多数据。

lib_emby_functions.py中的函数使用Emby的官方客户端SDK，该SDK很好地将服务器的REST API呈现为Python对象。然而，它有一些小bug，如果不修补，会导致Emby.MCP无法正确工作（因此需要在安装说明中提供的热修复补丁）。需要注意的是，Emby的REST API文档大量使用了CamelCaseNames，而SDK主要使用lower_case_delinated_names，因此需要仔细阅读SDK代码文件以了解如何正确命名。

文件lib_emby_debugging.py包含了一些对lib_emby_functions.py函数的基本交互式测试。它们不是完整的单元测试，但在这一轮开发个人项目时，我只想投入这么多精力。要激活它们，在emby_mcp_server.py顶部设置MY_DEBUG=True，然后交互式运行该脚本（而不是lib_emby_debugging.py）。

测试将写入标准输出，以便可以将其重定向到文件以捕获交互式终端可能截断的完整数据。提示和错误消息发送到标准错误，以便在重定向期间仍然可以进行交互。通过在lib_emby_debugging.py的测试块开头设置if True:而不是if False:来启用不同的测试块。

要调试MCP工具，可以安装SDK中包含的交互式客户端，这需要您拥有一个正在运行的Node.js环境。或者让LLM客户端为您执行测试，这意味着当出现问题时，您可能需要查阅LLM日志文件（Emby.MCP将有关严重问题的消息发送到标准错误，某些MCP客户端会将其写入日志文件）。

相关链接

• Model Context Protocol
• a16z播客与MCP联合创始人David Soria Parra
• Emby Server REST API文档
• Emby REST API客户端文档

许可证

版权所有 (C) 2025 Dominic Search code@angeltek.co.uk

本程序是自由软件：您可以在Free Software Foundation发布的第3版GNU通用公共许可证的条款下重新分发和/或修改它。

本程序的分发是希望它有用， 但没有任何保证；甚至没有适销性或特定用途适用性的隐含保证。请参阅 GNU通用公共许可证获取更多细节。

您应该已经收到了GNU通用公共许可证的副本。 如果没有，请访问https://www.gnu.org/licenses/。