Initial commit: Javis project

emby-mcp/README.md

@@ -0,0 +1,138 @@
+# 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