javis/emby-mcp/README.md

emby-mcp

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

Features

Tools:

• ping — verify connectivity / return Emby system info
• list_items — browse the media library with optional filtering
• search_items — search for items by name or metadata
• get_item — get detailed information about a specific item
• list_users — list all users on the server
• get_user — get user details
• list_sessions — see who's currently connected / watching
• system_info — get server system information
• playback_url — get a direct stream URL for an item
• playback_info — get detailed playback/transcoding options
• play_item — send remote control commands to start playback
• list_devices — list registered devices

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

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": "d:\\Javis\\emby-mcp\\.venv\\Scripts\\python.exe",
  "args": ["-m", "emby_mcp"],
  "env": {
    "EMBY_HOST": "emby.spaeth-bayern.de",
    "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", limit=50)

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