Emby。主控程序
模型上下文协议（MCP）服务器，其将Emby媒体服务器连接到AI客户端， 使用您自己的媒体收藏为任何符合MCP的LLM创建一种Amazon Alexa（tm）。个人MCP 以及Python学习练习，通过听Yoko Li谈论她而受到启发 摩尔斯电码MCP服务器.
请注意，这是一个独立的项目，与以下机构没有任何联系或认可：， Emby有限责任公司.
目录
特性 | 需求 | 安装 | 用法 | 引擎盖下 | 又见 | 许可证
特性
允许LLM通过MCP工具完成以下工作的最小可行项目：
- 登录和注销Emby媒体服务器；
- 检索媒体库列表；
- 选择指定的库；
- 检索该库中使用的流派列表；
- 按流派、项目标题、专辑名称、发行年份和歌词搜索该库中的项目，根据需要对响应进行分组；
- 检索播放列表，创建新的播放列表，向播放列表中添加项目并重新排序，以及与其他Emby用户共享播放列表；
- 检索Emby已知的可访问媒体播放器列表；
- 检索指定媒体播放器的当前播放队列；
- 控制指定媒体播放器的播放、暂停、查找等操作，包括将队列转移到另一个播放器。
需求
- python v3.13或更高版本
- 这 紫外线 包/项目经理
- 这 Python版MCP服务器SDK v1.94或更高版本
- 这 Emby客户端SDK 适用于Python v4.9.0.33，带有修补程序补丁（见下文）。
- A工作 Emby媒体服务器 具有本地或可通过网络访问的媒体文件库。
- MCP兼容的LLM/AI客户端。Emby。MCP是使用Claude Desktop开发的，但在撰写本文时 功能支持矩阵 -选择一个支持 工具.
- 支持MCP的LLM订阅计划（这可能需要付款）。
安装
以下说明适用于Windows 11 Pro上的全新安装-根据您自己的平台和需求进行调整。
安装Python | 安装Emby。主控程序 | 安装补丁 | 登录配置 | 基本检查 | 配置LLM
安装Python
- 安装 最新Python.自定义安装：可选功能=全选|高级选项=全选安装、关联文件、创建快捷方式、添加到环境、预编译。
- 从Powershell终端运行：
pip install uv- 通过Windows设置>系统>关于>高级>\[控制面板打开\]>环境变量>\[双击顶部用户部分的路径\]>\[窗口打开\]>新建，将uv添加到路径中。粘贴以下内容（将“313”更改为上面安装的Python版本，忽略第三个“.x”部分）：
%USERPROFILE%\AppData\Roaming\Python\Python313\Scripts
安装Emby。主控程序
- 创建空文件夹
\path\to\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 repo中）。
- 将以下内容粘贴到新的“.env”文件中，根据需要为您自己的服务器进行修改：
#------------
# 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
#------------- 您可能希望为Emby创建一个专用的Emby用户。MCP，这样你就可以限制它能做什么和能看到什么。
基本检查
此时，脚本应该能够通过访问Emby服务器来运行一些启动检查。
- 从Powershell终端运行：
cd "\path\to\Emby.MCP"
uv run emby_mcp_server.py- 这应该会产生类似于以下内容的输出（取决于您的Emby设置）：
Emby.MCP Copyright (C) 2025 Dominic Search
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.- 如果成功，请按Control-C或关闭Powershell终端以退出脚本。
配置LLM MCP客户端
- 添加Emby。通过从Powershell终端运行以下命令，将MCP集成到MCP SDK：
cd \path\to\Emby.MCP
uv run mcp install --name "Emby" --with "embyclient" emby_mcp_server.py- 使用以下说明选择客户端。如果您使用此处未列出的客户端，则需要自己调整这些说明。
克劳德桌面
Claude是一个很好的选择，作为一个通用的LLM聊天机器人，与Emby配合得很好。MCP，但需要付款。
- 安装 最新的克劳德桌面应用程序 在安装Python的同一台机器上。
- 你需要至少有一个 专业订阅 -不幸的是，免费计划不支持MCP：-|
- 编辑文件
%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json（点击Claude Desktop > File menu > Settings > Developer > Edit Config将打开此文件的文件资源管理器-在记事本或其他工具中编辑它）。修改使其看起来像这样，注意在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之前启动），情况尤其如此。没有埃姆比，克劳德将继续正常工作。MCP-只需在Emby服务器可用时重新启动Claude。
- 如果您在首次启动时因任何其他原因收到错误消息，请仔细检查中的路径
claude_desktop_config.json上面，尤其是它使用\\不是单身\在目录路径中。 - Emby。MCP将有关严重错误的消息发送到克劳德写入其日志文件的标准错误输出，因此请通读
%USERPROFILE%\AppData\Roaming\Claude\logs\mcp-server-Emby.log和%USERPROFILE%\AppData\Roaming\Claude\logs\mcp.log寻找线索。这可能会令人沮丧！
Microsoft Visual Studio代码
Visual Studio Code是开发人员的不错选择，它与MS Copilot集成，与Emby配合得相当好。主控程序
- 安装 最新的VS Code应用程序 在安装Python的同一台机器上。您至少需要v1.102才能获得完整的MCP支持。
- 你需要有一个 副驾驶 启用 ，以及安装并运行的相关VS代码扩展。你做 不 需要付费订阅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"
]
}
}
}- 启动并使用Emby。MCP服务器 官方VS代码文档.
用法
允许客户使用工具
当像Claude Desktop或VS Code这样的MCP客户端首次尝试使用新的MCP工具时，将出现一个弹出窗口，请求使用它的权限。为了避免每次都被询问，请按或选择 Allow always.
开始对话：
在对话开始时选择一个Emby库是个好主意，这样可以缩小搜索结果的范围，减少LLM必须处理的返回数据量（也就是说，如果你愿意，你可以在多个库中搜索）。例如，克劳德：
> 列出emby库 我会帮你探索你的Emby图书馆。让我先检查一下您的Emby服务器上有哪些库可用。 您的Emby服务器有几个可用库： - 音乐-主音乐库 - 播放列表-您保存的播放列表 - 电影-电影收藏 - BBC声音-BBC音频内容 > 选择bbc库 太好了！我已经选择了BBC声音图书馆。 现在，您可以在BBC Sounds库中搜索、浏览或探索内容。接下来你想做什么？
指导你的法学硕士
启动时，MCP客户端从Emby接收工具列表。MCP（所有具有 @mcp.tool() 在他们之前 def 行）以及参数名称和文档字符串的内容。
文档字符串是对工具、其参数及其输出的自然语言描述。由此，LLM 了解它手头的功能，并且非常善于推理哪些工具是 这是你给出的指示所必需的。但它并不完美，所以：
- 简短而具体，以减少LLM混淆。
- 通过提及Emby作为Emby的暗示来开始对话。应使用MCP工具。
- 如果你想根据短语搜索音频或视频 歌词 或 描述 然后明确
请在您的说明中注明，否则LLM可能只会搜索标题或艺术家。
- LLM试图不摄取大量数据，例如对大型库的模糊搜索。Emby。主控程序
通过以一口大小的块返回结果来解决这个问题。有时，即使这样也不够，所以你的指示 可能需要创造性地说服。
成绩单示例
我的Emby服务器包含许多BBC广播的音频戏剧文件，这些文件具有丰富的mp3/mp4元数据，包括一个长 歌词字段中带有完整演员列表的描述。这是展示Emby的好材料。MCP。.. 请参阅单独的文件 Claude Transcript.md示例
引擎盖下
Emby。MCP代码分为三个文件。 emby_mcp_server.py 包含所有与MCP相关的工具功能。在正常使用中，MCP不需要调用经典的“main”函数（尽管它在这里用于测试目的）。相反，MCP Server SDK解析声明为的函数 @mcp.tool() 并将其提供给MCP客户端进行直接呼叫。
在客户端启动时，会执行一些初步操作，包括实例化具有“寿命”功能的FastMCP app_lifespan. 这是一段异步代码，它登录到Emby服务器，初始化一些可更新的“上下文”存储（类似于全局变量），然后等待客户端退出（导致 app_lifespan 退出Emby）或被其他函数刺激以产生其存储（工具函数可以写入和读取上下文存储）。
MCP工具功能大多是内部功能的薄包装 lib_emby_functions.py 在那里进行重型吊装。这些包装器在编写时考虑了LLM理解，因此函数、参数和文档字符串的形式名称相当长 （请记住，MCP SDK将所有这些传递给LLM，以便它对工具有详细的了解）。他们只会回来 string-成功/错误消息或JSON格式的数据。
例外的是search_for_item（）和retrieve_next_search_chunk（），它们试图诱使LLM接受比它更多的数据 真的想把回报分成小块（由 LLM_MAX_ITEMS 变量在 .env 文件）。
功能在 lib_emby_functions.py 使用Emby的官方客户端SDK，它很好地展示了服务器的 作为Python对象的REST API。然而，它有一些小错误，如果不修补，就会阻止Emby。MCP无法正常工作 （因此需要上面安装说明中给出的修补程序）。需要注意的是，Emby的REST API文档 大量使用CamelCaseNames，而SDK主要使用较低的_case_delinated_name，因此可以很好地通读SDK代码 文件对于弄清楚如何正确命名事物是必要的。
文件 lib_emby_debugging.py 包含一些基本的交互式测试 lib_emby_functions.py 功能。 它们不是完整的单元测试，但是嘿，在这一轮开发个人项目时，我只想花那么多精力。 要激活它们，请设置 MY_DEBUG=True 在顶部 emby_mcp_server.py，然后以交互方式运行 *那* 脚本（不是 lib_emby_debugging.py).
测试写入标准输出，以便将其重定向到文件以捕获交互式终端可能截断的完整数据。提示和错误消息被发送到标准错误，以便在重定向过程中仍然可以进行交互。 在中启用不同的测试块 lib_emby_debugging.py 通过设置 if True: 而不是 if False: 在他们的开始。
要调试MCP工具，请安装SDK中包含的交互式客户端，这需要您有一个可用的Node.js 环境。或者让LLM客户端为您执行测试，这可能意味着在出现严重故障时需要费力地浏览LLM日志文件 （Emby.MCP将有关严重问题的消息发送到标准错误，一些MCP客户端会主动将其写入日志文件）。
又见
许可证
版权所有（C）2025多米尼克搜索
此程序是自由软件：您可以重新分发和/或修改它 根据发布的GNU通用公共许可证条款 自由软件基金会，许可证第3版。
分发此程序是希望它有用， 但不提供任何保证；甚至没有暗示的保证 适销性或特定用途的适用性。请参阅 GNU通用公共许可证了解更多详细信息。
您应该已经收到了GNU通用公共许可证的副本 随着这个程序。如果没有，请参阅 .