v1.0

emby-mcp/README.md

@@ -4,20 +4,23 @@ MCP (Model Context Protocol) server that exposes an **Emby** media server to LLM
 
 ## Features
 
-Tools:
+Tools (all read-only except `play_item`; failures are returned as MCP tool errors):
 - `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_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` — see who's currently connected / watching
+- `list_sessions` — connected clients, incl. `supports_remote_control` and what is playing
 - `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
+- `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
@@ -57,6 +60,13 @@ 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
@@ -79,10 +89,10 @@ Add to your `mcp_servers.json`:
 
 ```json
 "emby": {
-  "command": "d:\\Javis\\emby-mcp\\.venv\\Scripts\\python.exe",
+  "command": "F:\\Javis\\emby-mcp\\.venv\\Scripts\\python.exe",
   "args": ["-m", "emby_mcp"],
   "env": {
-    "EMBY_HOST": "emby.spaeth-bayern.de",
+    "EMBY_HOST": "http://10.0.0.5:8096",
     "EMBY_API_KEY": "your-api-key-here"
   },
   "transport": "stdio",
@@ -107,7 +117,14 @@ list_items(item_type="Movie")
 ### Search for content
 > "Find all episodes of Stranger Things"
 ```python
-search_items("Stranger Things", limit=50)
+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