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

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

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": "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?"
```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", limit=50)
```

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