javis/emby-mcp/README.md

emby-mcp

MCP (Model Context Protocol) server that exposes an Emby media server to LLM clients.

Features

Tools (all read-only except play_item; failures are returned as MCP tool errors):

• ping — verify connectivity / return Emby system info
• list_items(parent_id?, item_type?, limit, sort_by) — browse the media library
• search_items(query, item_type?, limit) — server-side search over the whole library
• get_item(item_id) — details incl. overview, genres, people, media sources
• list_users — list all users on the server
• get_user — get user details
• list_sessions — connected clients, incl. supports_remote_control and what is playing
• system_info — get server system information
• playback_url(item_id) — direct stream URL (returned without credentials)
• playback_info — media sources, codecs, direct-play / transcoding support
• play_item(item_id, device?, session_id?, play_command) — play on a remote-controllable client
• list_devices — list registered devices

IDs are URL-encoded, so a crafted ID such as 123/Delete or ../System/Restart cannot reach other Emby endpoints.

Resources:

• emby://library — snapshot of the entire media library as JSON
• emby://users — snapshot of all users as JSON
• emby://sessions — snapshot of current sessions as JSON

Prerequisites

• Python 3.10+
• An Emby server (can be tested against: emby.spaeth-bayern.de)
• An API Key from your Emby dashboard

Install

From this folder:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

Or using uv:

uv venv
uv pip install -e .

Configure

Copy .env.example to .env and fill in your Emby details:

EMBY_HOST=emby.spaeth-bayern.de
EMBY_API_KEY=your-api-key-here
EMBY_SCHEME=https
EMBY_TIMEOUT=10.0

EMBY_HOST may also be host:port or a full base URL (http://10.0.0.5:8096). EMBY_SCHEME defaults to http (Emby's own default on port 8096); set https only for a TLS endpoint such as a reverse proxy. EMBY_PORT is ignored when the host already contains a port. The .env file is read from the current working directory, so when Javis launches the server, put the settings into the env block of mcp_servers.json instead.

Get your API key from the Emby web dashboard: Dashboard → Users → Manage Users → [your user] → Settings → API Keys.

Run

.\run.bat
# or
python -m emby_mcp

Inspect with MCP Inspector

uv run mcp dev src/emby_mcp/server.py

Register in Claude Desktop / VS Code MCP config

Add to your mcp_servers.json:

"emby": {
  "command": "F:\\Javis\\emby-mcp\\.venv\\Scripts\\python.exe",
  "args": ["-m", "emby_mcp"],
  "env": {
    "EMBY_HOST": "http://10.0.0.5:8096",
    "EMBY_API_KEY": "your-api-key-here"
  },
  "transport": "stdio",
  "approval": "allow"
}

Usage Examples

Check connectivity

"Is my Emby server running?"

ping()

Browse library

"What movies do I have?"

list_items(item_type="Movie")

Search for content

"Find all episodes of Stranger Things"

search_items("Stranger Things", item_type="Episode", limit=50)

Play on a TV

"Play Stranger Things on the living-room TV"

search_items("Stranger Things")      # -> item id
play_item(item_id="...", device="TV")  # needs an open, remote-controllable Emby app

Check active sessions

"Who is watching something right now?"

list_sessions()

Get playback URL

"Get me a stream URL for this movie"

playback_url(item_id="...")

Project Layout

emby-mcp/
  pyproject.toml
  README.md
  .env.example
  run.bat
  src/emby_mcp/
    __init__.py
    __main__.py
    config.py
    client.py
    server.py