138 lines
2.8 KiB
Markdown
138 lines
2.8 KiB
Markdown
# 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 |