155 lines
3.8 KiB
Markdown
155 lines
3.8 KiB
Markdown
# 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 |