AI导哈

Emby媒体服务器管理工具

Emby MCP Server是一个基于Model Context Protocol的媒体服务器管理工具，提供44种工具用于监控、管理和故障排除Emby媒体服务器安装，适用于本地主机API访问和直接数据库检查。

  • by lefty3382
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lefty3382/emby-mcp

使用说明

Emby MCP服务器

A. 模型上下文协议 （MCP）服务器，用于完整的Emby媒体服务器管理。为AI助手提供8个类别的44个工具，用于监控、管理和排除Emby安装故障。

内置于 FastMCP 3.x，并设计为与Emby协同运行，用于localhost API访问和直接数据库检查。

特性

服务器和系统（4个工具）

  • get_server_info --服务器版本、操作系统、路径、Premiere状态
  • get_active_streams --当前播放的媒体包含转码详细信息
  • get_scheduled_tasks --所有具有状态、上次运行和触发器的计划任务
  • get_server_logs --按严重性和搜索词读取和过滤Emby服务器日志

用户和会话（9个工具）

  • list_users --所有拥有策略、访问权限和活动信息的用户
  • get_user_details --特定用户的详细资料
  • create_user / 删除用户 --用户生命周期管理
  • update_user --修改用户设置和策略
  • 重置密码 --重置用户密码
  • get_active_sessions --所有连接的设备和客户端
  • get_playback_历史 --每个用户的播放历史记录
  • set_library_access --控制用户可以查看哪些库

库（3个工具）

  • list_librarys --所有具有路径和集合类型的虚拟文件夹
  • get_library_stats --每个库的项目计数和大小
  • 扫描库 --触发库扫描（完整扫描或按库ID扫描）

项目和搜索（7个工具）

  • get_movies --通过排序和过滤浏览电影
  • get_series / get_原因 / get_episodes --电视节目层次浏览
  • get_item_details --任何项目的完整元数据（媒体信息、路径、流）
  • 获取最近添加的内容 --各图书馆的最新补充
  • 搜索项目 --跨所有媒体类型的全文搜索

播放列表和收藏（5个工具）

  • list_playlists --所有包含项目计数的播放列表
  • 创建播放列表 --创建新播放列表
  • get_playlist_items --列出播放列表中的项目
  • add_playlist_items --将项目添加到现有播放列表
  • list_collections --浏览电影/电视收藏

数据库（8个工具）

  • 查询数据库 --对任何Emby数据库运行只读SQL查询
  • get_db_table_info --架构发现（表、列、行数）
  • get_db统计 --数据库文件大小、WAL状态、完整性
  • get_emby_connect_status --所有用户的Emby Connect链接详细信息
  • 检查播放列表完整性 -交叉参考数据库与API播放列表数据
  • 审计路径 --扫描媒体路径并标记与预期前缀不匹配的情况
  • 路径_手术 --在library.db中查找/替换路径前缀（安全门控）
  • 删除播放列表 --从数据库中删除播放列表（安全门控）

报告和分析（6个工具）

  • 图书馆报告 --每个图书馆的项目计数和位置
  • media_type_report --按媒体类型列出的跨库统计数据
  • 回放报告 --观看次数和播放次数最多
  • 用户活动报告 --每个用户的参与度和访问状态
  • 媒体_完整性_报告 --将数据库项与磁盘上的文件进行比较
  • 存储报告 --按介质装载和数据库大小划分的存储使用情况

诊断和故障排除（4个工具）

  • 分析日志 --通过计数和时间窗口分析日志中的错误模式
  • 转码诊断 --带有GPU/CPU详细信息的活动转码会话
  • 连接性检查 -验证API、数据库、装载、GPU和容器运行状况
  • 故障排除_回放 --通过关联会话和日志来诊断播放问题

建筑

两个异步后端：

  • EmbyClient -具有惰性会话管理的异步REST API包装器（aiohttp）
  • Emby数据库 --用于直接数据库查询的异步SQLite访问（aiosqlite）

数据库写入安全门

所有数据库写入操作（path_surgery、delete_playlist）都强制执行5个安全门：

  1. 需要确认 --默认情况下为预览模式，必须通过 confirm=true 执行
  2. 集装箱检查 --在执行任何写入操作之前，验证Emby容器是否已停止
  3. WAL验证 --确认不存在WAL/SHM文件（完全关闭）
  4. 自动备份 --在写入之前将数据库复制到带时间戳的备份中
  5. 完整性检查 --跑步 PRAGMA integrity_check 写作后

部署

设计为在同一主机上与Emby一起作为Docker容器运行。这使得：

  • 本地主机API访问（快速，无网络延迟）
  • 直接文件系统访问Emby的程序数据（数据库、日志）
  • Docker套接字访问以检查Emby容器状态（用于写安全门）
  • 对媒体库装载的只读访问（用于完整性检查）

先决条件

  • Docker和Docker Compose
  • Emby API键（仪表板>高级>API键）
  • Emby程序数据目录可在主机上访问

快速开始

  1. 克隆存储库：

    git clone https://github.com/lefty3382/emby-mcp.git
cd emby-mcp

  2. 复制 .env.example 到 .env 并配置：

    cp .env.example .env

    所需设置：

    EMBY_API_KEY=your-api-key-here
EMBY_CONFIG_HOST_PATH=/path/to/emby/programdata

    可选设置：

    EMBY_HOST=emby                    # Emby hostname (use Docker service name if on same network)
EMBY_PORT=8096                    # Emby HTTP port
EMBY_MEDIA_PATHS=/mnt/movies,/mnt/tv   # Comma-separated media mount paths (inside container)
MCP_PORT=8486                     # MCP server port

  3. 将媒体库卷装载添加到 docker-compose.yaml:

    volumes:
  - /path/to/movies:/mnt/movies:ro
  - /path/to/tv:/mnt/tv:ro

  4. 构建和启动：

    docker compose up -d

  5. 配置您的MCP客户端：

    # Claude Code
claude mcp add emby --transport http http://<host>:8486/mcp --scope user

与Emby在相同的Docker网络上运行

如果Emby在同一台主机上运行Docker，请添加 emby-mcp 到同一个Docker Compose文件或Docker网络，这样它就可以通过Docker DNS访问Emby(emby):

services:
  emby:
    image: emby/embyserver:latest
    container_name: emby
    # ... your Emby config ...

  emby-mcp:
    build: .
    container_name: emby-mcp
    environment:
      - EMBY_HOST=emby          # Docker DNS name
      - EMBY_API_KEY=${EMBY_API_KEY}
      - EMBY_CONFIG_PATH=/emby-config
      - EMBY_MEDIA_PATHS=/mnt/movies,/mnt/tv
      - MCP_PORT=8486
    volumes:
      - /path/to/emby/programdata:/emby-config
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /path/to/movies:/mnt/movies:ro
      - /path/to/tv:/mnt/tv:ro
    ports:
      - "8486:8486"
    restart: unless-stopped
    depends_on:
      - emby

配置

环境变量 必填 默认 描述
EMBY_API_KEY 是 - Emby API密钥用于REST API身份验证
EMBY_HOST 没有 emby Emby服务器主机名或IP
EMBY_PORT 没有 8096 Emby服务器HTTP端口
EMBY_CONFIG_PATH 没有 /emby-config 容器内Emby程序数据的路径
EMBY_CONFIG_HOST_PATH 是* -- Emby程序数据的主机路径（由docker compose使用）
EMBY_MEDIA_PATHS 否 -- 逗号分隔的媒体装载路径（例如。， /mnt/movies,/mnt/tv)
MCP_PORT 没有 8486 MCP服务器的端口

*使用提供的时需要 docker-compose.yaml.

技术

  • Python 3.12 始终使用async/await
  • FastMCP 3.1.0 --带流式HTTP传输的MCP服务器框架（无状态模式）
  • 意图tp -用于Emby REST API的异步HTTP客户端
  • aiosqlite --用于直接数据库查询的异步SQLite访问

许可证

麻省理工学院

相关 MCP