Emby.MCP

Emby.MCP connects your Emby media server to an AI client via the MCP Tools, enabling an LLM to interact with your media library. Once running, you can log in to the Emby server, fetch library lists, select a library, query genres, and search items by various fields such as title, genre, year, or lyrics. It also supports playlist management (retrieve, create, add items, reorder, share) and provides access to available media players and their queues, with controls to play, pause, seek, and transfer queues between players. The design makes it possible to build an Alexa-like experience around your own Emby collection using any MCP-compatible LLM client, including Claude Desktop and other supported clients. To get started, run the server with your Emby credentials and connect an MCP client that supports Tools, then issue natural-language commands like “Show me all action movies in 1080p” or “Add ‘Inception’ to my Watchlist.”

Prerequisites:

• Python 3.13 or higher
• The uv package/project manager for Python
• An Emby Media Server accessible from the machine running this MCP server
• An MCP-compatible LLM client (e.g., Claude Desktop) with Tools support

Installation steps:

1. Install Python 3.13+ on your system.
2. Install uv (Python package manager used by MCP servers):

pip install uv

3. Obtain the Emby.MCP files and place them in a folder of your choice, e.g. C:\path\to\Emby.MCP on Windows or /path/to/Emby.MCP on Unix-like systems.
4. From the terminal, navigate to the Emby.MCP folder and sync dependencies (this example uses uv as in the README):

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

5. Create and populate a .env file with Emby credentials in the Emby.MCP folder (as described in the README):

# Emby.MCP/.env
EMBY_SERVER_URL = "http://localhost:8096"
EMBY_USERNAME = "user"
EMBY_PASSWORD = "pass"
EMBY_VERIFY_SSL = True
LLM_MAX_ITEMS = 100

6. Run startup checks to verify connectivity to Emby:

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

7. Install the MCP client integration (example shown for the CLI workflow):

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

8. Configure your MCP client (Claude Desktop or other) to connect to this Emby.MCP instance using the given example configuration from the README or the client’s integration guidance.

Tips and known considerations:

• Ensure the Emby credentials in .env have appropriate access and avoid exposing them.
• If you run Claude Desktop or another MCP client on the same host, ensure the client can reach the Emby.MCP server and that the MCP Tools are enabled in the client configuration.
• The Emby client SDK patches mentioned in the README are important for reliability with certain Emby builds; apply them per the provided instructions when you set up or upgrade.
• If SSL verification is disabled (EMBY_VERIFY_SSL=False), be mindful of potential security risks in production environments.
• The LLM_MAX_ITEMS setting helps bound responses; adjust according to your LLM’s context window and latency trade-offs.
• When updating Emby.MCP or dependencies, re-run the uv sync and re-apply hotfix patches as described in the installation notes to keep compatibility with Emby SDK changes.