# 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:

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

Or using `uv`:

```powershell
uv venv
uv pip install -e .
```

## Configure

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

```ini
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

```powershell
.\run.bat
# or
python -m emby_mcp
```

### Inspect with MCP Inspector

```powershell
uv run mcp dev src/emby_mcp/server.py
```

## Register in Claude Desktop / VS Code MCP config

Add to your `mcp_servers.json`:

```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?"
```python
ping()
```

### Browse library
> "What movies do I have?"
```python
list_items(item_type="Movie")
```

### Search for content
> "Find all episodes of Stranger Things"
```python
search_items("Stranger Things", item_type="Episode", limit=50)
```

### Play on a TV
> "Play Stranger Things on the living-room TV"
```python
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?"
```python
list_sessions()
```

### Get playback URL
> "Get me a stream URL for this movie"
```python
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