ha-gronod-addons/emby-mcp/README.md

Emby MCP

Emby Model Context Protocol (MCP) server with a Home Assistant REST bridge, packaged as a Home Assistant add-on.

Connect your Emby media server to AI clients and Home Assistant voice/conversation agents — search the library, browse shows and episodes, manage playlists, see what's playing, and control playback, all through natural-language tool calls.

Features

• Streamable MCP endpoint at /mcp for Claude, ChatGPT, and other MCP clients
• REST tool bridge at /call/{tool} designed for Home Assistant conversation agents (works with Assist functions)
• Search films, TV series, episodes, and music with chunked results for large libraries
• Browse item children, series seasons, and episode lists with per-user played state and resume positions
• Resolve the next episode to watch (next_unplayed/latest)
• Create and modify playlists; list player sessions and control playback (PlayNow, pause, seek, skip)
• Inspect and switch audio/subtitle tracks mid-playback
• Localhost-restricted mode (default): only Home Assistant itself can call the bridge, using stored credentials — no per-request auth needed

Requirements

• A running Emby server reachable from Home Assistant
• Emby credentials: username + password, or an API key (+ user ID)

Installation

1. Add this repository to Home Assistant (Settings → Add-ons → Add-on Store → ⋮ → Repositories): https://git.i3omb.com/gronod/ha-gronod-addons
2. Install Emby MCP from the add-on store
3. Set emby_server_url plus emby_username/emby_password (or emby_api_key + emby_user_id), leave Restrict to localhost on, and start the add-on

See DOCS.md for the full option reference, conversation-agent setup, troubleshooting, and standalone (non-add-on) usage.

License

© 2026 Gordon Bolton. Based on Emby.MCP; this is a complete rewrite. GPL v3 — see LICENCE.md.