mcp-plex-server 0.1.3__tar.gz

mcp_plex_server-0.1.3/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mcp-plex-server
+Version: 0.1.3
+Summary: MCP server for Plex media discovery, search, and library management
+Keywords: mcp,plex,media,model-context-protocol
+Author: Matthew O'Brien
+Author-email: Matthew O'Brien <obrien.mlotwis@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Dist: mcp>=1.27.0,<2
+Requires-Dist: plexapi>=4.16.0
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/obrien-matthew/mcp-plex
+Project-URL: Issues, https://github.com/obrien-matthew/mcp-plex/issues
+Description-Content-Type: text/markdown
+
+# mcp-plex
+
+MCP server for Plex Media Server, focused on media discovery, search, and library management. 13 granular tools designed for use with Claude and other LLM agents.
+
+## Prerequisites
+
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+- A running [Plex Media Server](https://www.plex.tv/)
+- A Plex authentication token
+
+## Setup
+
+### 1. Get Your Plex Token
+
+The easiest way to find your Plex token:
+
+1. Sign in to [Plex Web App](https://app.plex.tv)
+2. Browse to any media item and click **Get Info** (or **...** > **Get Info**)
+3. Click **View XML** in the bottom-left
+4. In the URL bar, find the `X-Plex-Token=` parameter -- that's your token
+
+Alternatively, check the [Plex support article](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) for other methods.
+
+### 2. Install
+
+```bash
+cd mcp-plex
+uv sync
+```
+
+### 3. Configure Environment Variables
+
+Set these before running the server:
+
+```bash
+export PLEX_SERVER_URL="http://your-plex-server:32400"
+export PLEX_TOKEN="your_plex_token"
+```
+
+### 4. Test the Connection
+
+```bash
+uv run mcp-plex
+```
+
+The server connects to your Plex server on startup and verifies the token. If the connection fails, check that your server URL and token are correct.
+
+## Claude Desktop / Claude Code Configuration
+
+Add to your MCP server config. If installed from PyPI:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "command": "uvx",
+      "args": ["mcp-plex"],
+      "env": {
+        "PLEX_SERVER_URL": "http://your-plex-server:32400",
+        "PLEX_TOKEN": "your_plex_token"
+      }
+    }
+  }
+}
+```
+
+Or if running from a local clone:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mcp-plex", "run", "mcp-plex"],
+      "env": {
+        "PLEX_SERVER_URL": "http://your-plex-server:32400",
+        "PLEX_TOKEN": "your_plex_token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Discovery
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `search_media` | `query`, `media_type=""`, `limit=20` | Search across all libraries. Optional type filter: "movie", "show", "episode", "artist", "album", "track". |
+| `get_recently_added` | `limit=20`, `library_name=""` | Recently added media, optionally filtered to a library. |
+| `get_on_deck` | `limit=10` | Continue watching / next episode list. |
+
+### Library Browsing
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_libraries` | (none) | List all library sections with types and item counts. |
+| `get_library_contents` | `library_name`, `sort="titleSort"`, `limit=50` | Browse a library. Sort by title, date added, year, or rating. |
+| `get_media_details` | `rating_key` | Full details for one item: summary, genres, cast, directors, ratings. |
+| `get_library_stats` | `library_name=""` | Item counts and stats for one or all libraries. |
+
+### Shows
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_seasons` | `rating_key` | List seasons for a TV show. |
+| `get_episodes` | `rating_key`, `season_number=0` | List episodes (all or by season). |
+
+### Collections & Playlists
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_collections` | `library_name` | List collections in a library. |
+| `get_playlists` | (none) | List all playlists on the server. |
+| `get_playlist_items` | `rating_key` | Get items in a playlist. |
+
+### Management
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `scan_library` | `library_name` | Trigger a background library scan. |
+
+## Development
+
+```bash
+uv run mcp-plex              # Run the server
+uv run ruff check src/       # Lint
+uv run ruff format src/      # Format
+uv run pyright src/          # Type check
+```
+
+### Pre-commit Hooks
+
+This project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit checks. Install with `brew install lefthook` (or see [other install methods](https://github.com/evilmartians/lefthook/blob/master/docs/install.md)), then:
+
+```bash
+lefthook install
+```

mcp_plex_server-0.1.3/README.md

@@ -0,0 +1,140 @@
+# mcp-plex
+
+MCP server for Plex Media Server, focused on media discovery, search, and library management. 13 granular tools designed for use with Claude and other LLM agents.
+
+## Prerequisites
+
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+- A running [Plex Media Server](https://www.plex.tv/)
+- A Plex authentication token
+
+## Setup
+
+### 1. Get Your Plex Token
+
+The easiest way to find your Plex token:
+
+1. Sign in to [Plex Web App](https://app.plex.tv)
+2. Browse to any media item and click **Get Info** (or **...** > **Get Info**)
+3. Click **View XML** in the bottom-left
+4. In the URL bar, find the `X-Plex-Token=` parameter -- that's your token
+
+Alternatively, check the [Plex support article](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) for other methods.
+
+### 2. Install
+
+```bash
+cd mcp-plex
+uv sync
+```
+
+### 3. Configure Environment Variables
+
+Set these before running the server:
+
+```bash
+export PLEX_SERVER_URL="http://your-plex-server:32400"
+export PLEX_TOKEN="your_plex_token"
+```
+
+### 4. Test the Connection
+
+```bash
+uv run mcp-plex
+```
+
+The server connects to your Plex server on startup and verifies the token. If the connection fails, check that your server URL and token are correct.
+
+## Claude Desktop / Claude Code Configuration
+
+Add to your MCP server config. If installed from PyPI:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "command": "uvx",
+      "args": ["mcp-plex"],
+      "env": {
+        "PLEX_SERVER_URL": "http://your-plex-server:32400",
+        "PLEX_TOKEN": "your_plex_token"
+      }
+    }
+  }
+}
+```
+
+Or if running from a local clone:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mcp-plex", "run", "mcp-plex"],
+      "env": {
+        "PLEX_SERVER_URL": "http://your-plex-server:32400",
+        "PLEX_TOKEN": "your_plex_token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Discovery
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `search_media` | `query`, `media_type=""`, `limit=20` | Search across all libraries. Optional type filter: "movie", "show", "episode", "artist", "album", "track". |
+| `get_recently_added` | `limit=20`, `library_name=""` | Recently added media, optionally filtered to a library. |
+| `get_on_deck` | `limit=10` | Continue watching / next episode list. |
+
+### Library Browsing
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_libraries` | (none) | List all library sections with types and item counts. |
+| `get_library_contents` | `library_name`, `sort="titleSort"`, `limit=50` | Browse a library. Sort by title, date added, year, or rating. |
+| `get_media_details` | `rating_key` | Full details for one item: summary, genres, cast, directors, ratings. |
+| `get_library_stats` | `library_name=""` | Item counts and stats for one or all libraries. |
+
+### Shows
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_seasons` | `rating_key` | List seasons for a TV show. |
+| `get_episodes` | `rating_key`, `season_number=0` | List episodes (all or by season). |
+
+### Collections & Playlists
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `get_collections` | `library_name` | List collections in a library. |
+| `get_playlists` | (none) | List all playlists on the server. |
+| `get_playlist_items` | `rating_key` | Get items in a playlist. |
+
+### Management
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `scan_library` | `library_name` | Trigger a background library scan. |
+
+## Development
+
+```bash
+uv run mcp-plex              # Run the server
+uv run ruff check src/       # Lint
+uv run ruff format src/      # Format
+uv run pyright src/          # Type check
+```
+
+### Pre-commit Hooks
+
+This project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit checks. Install with `brew install lefthook` (or see [other install methods](https://github.com/evilmartians/lefthook/blob/master/docs/install.md)), then:
+
+```bash
+lefthook install
+```

mcp_plex_server-0.1.3/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "mcp-plex-server"
+version = "0.1.3"
+description = "MCP server for Plex media discovery, search, and library management"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Matthew O'Brien", email = "obrien.mlotwis@gmail.com" }
+]
+requires-python = ">=3.14"
+keywords = ["mcp", "plex", "media", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = [
+    "mcp>=1.27.0,<2",
+    "plexapi>=4.16.0",
+]
+
+[project.urls]
+Repository = "https://github.com/obrien-matthew/mcp-plex"
+Issues = "https://github.com/obrien-matthew/mcp-plex/issues"
+
+[tool.uv.build-backend]
+module-name = "plex_mcp"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.11.0",
+    "pyright>=1.1.400",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"
+
+[project.scripts]
+mcp-plex = "plex_mcp:main"

mcp_plex_server-0.1.3/src/plex_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""MCP server for Plex media discovery, search, and library management."""
+
+from .server import mcp
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+__all__ = ["main", "mcp"]

mcp_plex_server-0.1.3/src/plex_mcp/auth.py

@@ -0,0 +1,45 @@
+"""Plex server connection and authenticated client singleton."""
+
+import os
+import sys
+
+from plexapi.server import PlexServer
+
+_server: PlexServer | None = None
+
+
+def get_plex_server() -> PlexServer:
+    """Return a cached, authenticated Plex server connection.
+
+    Reads PLEX_SERVER_URL and PLEX_TOKEN from environment variables.
+
+    Raises RuntimeError if required env vars are missing or connection fails.
+    """
+    global _server
+    if _server is not None:
+        return _server
+
+    server_url = os.environ.get("PLEX_SERVER_URL")
+    token = os.environ.get("PLEX_TOKEN")
+
+    if not server_url or not token:
+        raise RuntimeError(
+            "PLEX_SERVER_URL and PLEX_TOKEN environment variables "
+            "are required. See README.md for setup instructions."
+        )
+
+    # Strip trailing slash for consistency
+    server_url = server_url.rstrip("/")
+
+    try:
+        _server = PlexServer(server_url, token)
+        # Verify connection by fetching library sections
+        _server.library.sections()
+    except Exception as e:
+        _server = None
+        print(f"Plex connection failed: {e}", file=sys.stderr)
+        raise RuntimeError(
+            "Failed to connect to Plex server. Please check your server URL and token."
+        ) from e
+
+    return _server

mcp_plex_server-0.1.3/src/plex_mcp/client.py

@@ -0,0 +1,226 @@
+"""Thin wrapper over plexapi with input validation and clean error handling."""
+
+import sys
+from typing import NoReturn
+
+from plexapi.exceptions import BadRequest, NotFound, Unauthorized
+
+from .auth import get_plex_server
+from .formatting import (
+    format_collection,
+    format_library,
+    format_media_item,
+    format_media_item_detailed,
+    format_playlist,
+    format_season,
+)
+from .validation import validate_limit, validate_rating_key
+
+
+class PlexError(Exception):
+    """User-facing Plex API error."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class PlexClient:
+    """Validated, formatted interface to the Plex API."""
+
+    def __init__(self) -> None:
+        self._plex = get_plex_server()
+
+    def _handle_error(self, e: Exception, action: str) -> NoReturn:
+        msg = f"Plex API error while {action}"
+        status_code: int | None = None
+        if isinstance(e, NotFound):
+            msg = f"Not found while {action}"
+            status_code = 404
+        elif isinstance(e, Unauthorized):
+            msg = f"Unauthorized while {action}"
+            status_code = 401
+        elif isinstance(e, BadRequest):
+            msg = f"Bad request while {action}"
+            status_code = 400
+        print(f"{msg}: {e}", file=sys.stderr)
+        raise PlexError(msg, status_code) from e
+
+    def _get_library(self, library_name: str):
+        """Get a library section by name."""
+        try:
+            return self._plex.library.section(library_name)
+        except NotFound as e:
+            available = [s.title for s in self._plex.library.sections()]
+            raise PlexError(
+                f"Library '{library_name}' not found. "
+                f"Available libraries: {', '.join(available)}"
+            ) from e
+
+    # -- Discovery --
+
+    def search_media(
+        self, query: str, media_type: str = "", limit: int = 20
+    ) -> list[dict]:
+        limit = validate_limit(limit)
+        try:
+            if media_type:
+                results = self._plex.search(query, mediatype=media_type, limit=limit)
+            else:
+                results = self._plex.search(query, limit=limit)
+            return [format_media_item(item) for item in results[:limit]]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "searching media")
+
+    def get_recently_added(self, limit: int = 20, library_name: str = "") -> list[dict]:
+        limit = validate_limit(limit)
+        try:
+            if library_name:
+                section = self._get_library(library_name)
+                items = section.recentlyAdded(maxresults=limit)
+            else:
+                items = self._plex.library.recentlyAdded(maxresults=limit)
+            return [format_media_item(item) for item in items]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching recently added")
+
+    def get_on_deck(self, limit: int = 10) -> list[dict]:
+        limit = validate_limit(limit)
+        try:
+            items = self._plex.library.onDeck(maxresults=limit)
+            return [format_media_item(item) for item in items]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching on deck")
+
+    # -- Library Browsing --
+
+    def get_libraries(self) -> list[dict]:
+        try:
+            sections = self._plex.library.sections()
+            return [format_library(s) for s in sections]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching libraries")
+
+    def get_library_contents(
+        self, library_name: str, sort: str = "titleSort", limit: int = 50
+    ) -> list[dict]:
+        limit = validate_limit(limit, max_val=100)
+        try:
+            section = self._get_library(library_name)
+            items = section.all(sort=sort)[:limit]
+            return [format_media_item(item) for item in items]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching library contents")
+
+    def get_media_details(self, rating_key: str) -> dict:
+        rating_key = validate_rating_key(rating_key)
+        try:
+            item = self._fetch_item(rating_key, "fetching media details")
+            return format_media_item_detailed(item)
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching media details")
+
+    def get_library_stats(self, library_name: str = "") -> dict | list[dict]:
+        try:
+            if library_name:
+                section = self._get_library(library_name)
+                return {
+                    "title": section.title,
+                    "type": section.type,
+                    "total_items": section.totalSize,
+                    "total_viewable": section.totalViewSize(),
+                }
+            sections = self._plex.library.sections()
+            return [
+                {
+                    "title": s.title,
+                    "type": s.type,
+                    "total_items": s.totalSize,
+                }
+                for s in sections
+            ]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching library stats")
+
+    # -- Shows --
+
+    def _fetch_item(self, rating_key: str, action: str) -> object:
+        """Fetch an item by rating key, raising PlexError if not found."""
+        item = self._plex.fetchItem(int(rating_key))
+        if item is None:
+            raise PlexError(f"Item {rating_key} not found")
+        return item
+
+    def get_seasons(self, rating_key: str) -> list[dict]:
+        rating_key = validate_rating_key(rating_key)
+        try:
+            show = self._fetch_item(rating_key, "fetching seasons")
+            if not hasattr(show, "seasons"):
+                raise PlexError(
+                    f"Item {rating_key} is not a TV show"
+                    f" (type: {getattr(show, 'type', 'unknown')})"
+                )
+            return [format_season(s) for s in show.seasons()]  # type: ignore[union-attr]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching seasons")
+
+    def get_episodes(self, rating_key: str, season_number: int = 0) -> list[dict]:
+        rating_key = validate_rating_key(rating_key)
+        try:
+            item = self._fetch_item(rating_key, "fetching episodes")
+            if hasattr(item, "episodes"):
+                # It's a show -- get all episodes or filter by season
+                if season_number > 0:
+                    season = item.season(season_number)  # type: ignore[union-attr]
+                    episodes = season.episodes()
+                else:
+                    episodes = item.episodes()  # type: ignore[union-attr]
+            else:
+                raise PlexError(
+                    f"Item {rating_key} is not a show or season"
+                    f" (type: {getattr(item, 'type', 'unknown')})"
+                )
+            return [format_media_item(ep) for ep in episodes]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching episodes")
+
+    # -- Collections & Playlists --
+
+    def get_collections(self, library_name: str) -> list[dict]:
+        try:
+            section = self._get_library(library_name)
+            collections = section.collections()
+            return [format_collection(c) for c in collections]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching collections")
+
+    def get_playlists(self) -> list[dict]:
+        try:
+            playlists = self._plex.playlists()
+            return [format_playlist(p) for p in playlists]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching playlists")
+
+    def get_playlist_items(self, rating_key: str) -> list[dict]:
+        rating_key = validate_rating_key(rating_key)
+        try:
+            playlist = self._fetch_item(rating_key, "fetching playlist items")
+            if not hasattr(playlist, "items"):
+                raise PlexError(
+                    f"Item {rating_key} is not a playlist"
+                    f" (type: {getattr(playlist, 'type', 'unknown')})"
+                )
+            return [format_media_item(item) for item in playlist.items()]  # type: ignore[union-attr]
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "fetching playlist items")
+
+    # -- Management --
+
+    def scan_library(self, library_name: str) -> str:
+        try:
+            section = self._get_library(library_name)
+            section.update()
+            return f"Library scan started for '{library_name}'."
+        except (NotFound, BadRequest, Unauthorized) as e:
+            self._handle_error(e, "scanning library")

mcp_plex_server-0.1.3/src/plex_mcp/formatting.py

@@ -0,0 +1,212 @@
+"""Response formatters that produce clean, LLM-friendly dicts.
+
+Only includes fields useful for an LLM -- no images, file paths, or internal IDs.
+"""
+
+from datetime import datetime
+from typing import Any
+
+
+def _safe_attr(obj: Any, attr: str, default: Any = None) -> Any:
+    """Get an attribute safely, returning default if missing or None."""
+    return getattr(obj, attr, default) or default
+
+
+def _format_datetime(dt: datetime | None) -> str | None:
+    """Format a datetime as an ISO string, or return None."""
+    if dt is None:
+        return None
+    return dt.isoformat()
+
+
+def _format_duration(ms: int | None) -> str | None:
+    """Format milliseconds as a human-readable duration."""
+    if ms is None:
+        return None
+    total_seconds = ms // 1000
+    hours, remainder = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours > 0:
+        return f"{hours}h {minutes}m"
+    return f"{minutes}m {seconds}s"
+
+
+def format_media_item(item: Any) -> dict:
+    """Format any Plex media item into an LLM-friendly dict.
+
+    Routes to the appropriate formatter based on item type.
+    """
+    item_type = str(_safe_attr(item, "type", "unknown"))
+    formatters = {
+        "movie": _format_movie,
+        "show": _format_show,
+        "season": _format_season_item,
+        "episode": _format_episode,
+        "artist": _format_artist,
+        "album": _format_album,
+        "track": _format_track,
+    }
+    formatter = formatters.get(item_type, _format_generic)
+    return formatter(item)
+
+
+def format_media_item_detailed(item: Any) -> dict:
+    """Format a media item with full detail (for get_media_details)."""
+    result = format_media_item(item)
+    # Add extended fields
+    summary = _safe_attr(item, "summary")
+    if summary:
+        result["summary"] = str(summary)
+
+    genres = _safe_attr(item, "genres", [])
+    if genres:
+        result["genres"] = [str(g.tag) for g in genres]
+
+    roles = _safe_attr(item, "roles", [])
+    if roles:
+        result["cast"] = [str(r.tag) for r in roles[:10]]
+
+    directors = _safe_attr(item, "directors", [])
+    if directors:
+        result["directors"] = [str(d.tag) for d in directors]
+
+    writers = _safe_attr(item, "writers", [])
+    if writers:
+        result["writers"] = [str(w.tag) for w in writers]
+
+    studio = _safe_attr(item, "studio")
+    if studio:
+        result["studio"] = str(studio)
+
+    content_rating = _safe_attr(item, "contentRating")
+    if content_rating:
+        result["content_rating"] = str(content_rating)
+
+    return result
+
+
+def _format_movie(item: Any) -> dict:
+    return {
+        "type": "movie",
+        "title": str(_safe_attr(item, "title", "")),
+        "year": _safe_attr(item, "year"),
+        "rating": _safe_attr(item, "rating"),
+        "audience_rating": _safe_attr(item, "audienceRating"),
+        "duration": _format_duration(_safe_attr(item, "duration")),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+        "added_at": _format_datetime(_safe_attr(item, "addedAt")),
+    }
+
+
+def _format_show(item: Any) -> dict:
+    return {
+        "type": "show",
+        "title": str(_safe_attr(item, "title", "")),
+        "year": _safe_attr(item, "year"),
+        "rating": _safe_attr(item, "rating"),
+        "audience_rating": _safe_attr(item, "audienceRating"),
+        "season_count": _safe_attr(item, "childCount"),
+        "episode_count": _safe_attr(item, "leafCount"),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+        "added_at": _format_datetime(_safe_attr(item, "addedAt")),
+    }
+
+
+def _format_season_item(item: Any) -> dict:
+    return {
+        "type": "season",
+        "title": str(_safe_attr(item, "title", "")),
+        "show_title": str(_safe_attr(item, "parentTitle", "")),
+        "season_number": _safe_attr(item, "index"),
+        "episode_count": _safe_attr(item, "leafCount"),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+    }
+
+
+def _format_episode(item: Any) -> dict:
+    return {
+        "type": "episode",
+        "title": str(_safe_attr(item, "title", "")),
+        "show_title": str(_safe_attr(item, "grandparentTitle", "")),
+        "season_number": _safe_attr(item, "parentIndex"),
+        "episode_number": _safe_attr(item, "index"),
+        "duration": _format_duration(_safe_attr(item, "duration")),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+    }
+
+
+def _format_artist(item: Any) -> dict:
+    return {
+        "type": "artist",
+        "title": str(_safe_attr(item, "title", "")),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+        "added_at": _format_datetime(_safe_attr(item, "addedAt")),
+    }
+
+
+def _format_album(item: Any) -> dict:
+    return {
+        "type": "album",
+        "title": str(_safe_attr(item, "title", "")),
+        "artist": str(_safe_attr(item, "parentTitle", "")),
+        "year": _safe_attr(item, "year"),
+        "track_count": _safe_attr(item, "leafCount"),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+        "added_at": _format_datetime(_safe_attr(item, "addedAt")),
+    }
+
+
+def _format_track(item: Any) -> dict:
+    return {
+        "type": "track",
+        "title": str(_safe_attr(item, "title", "")),
+        "artist": str(_safe_attr(item, "grandparentTitle", "")),
+        "album": str(_safe_attr(item, "parentTitle", "")),
+        "track_number": _safe_attr(item, "index"),
+        "duration": _format_duration(_safe_attr(item, "duration")),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+    }
+
+
+def _format_generic(item: Any) -> dict:
+    return {
+        "type": str(_safe_attr(item, "type", "unknown")),
+        "title": str(_safe_attr(item, "title", "")),
+        "rating_key": str(_safe_attr(item, "ratingKey", "")),
+    }
+
+
+def format_library(section: Any) -> dict:
+    """Format a library section for listing."""
+    return {
+        "title": str(_safe_attr(section, "title", "")),
+        "type": str(_safe_attr(section, "type", "")),
+        "key": str(_safe_attr(section, "key", "")),
+        "total_items": _safe_attr(section, "totalSize"),
+        "updated_at": _format_datetime(_safe_attr(section, "updatedAt")),
+    }
+
+
+def format_season(season: Any) -> dict:
+    """Format a season for listing."""
+    return _format_season_item(season)
+
+
+def format_playlist(playlist: Any) -> dict:
+    """Format a playlist for listing."""
+    return {
+        "title": str(_safe_attr(playlist, "title", "")),
+        "playlist_type": str(_safe_attr(playlist, "playlistType", "")),
+        "item_count": _safe_attr(playlist, "leafCount"),
+        "duration": _format_duration(_safe_attr(playlist, "duration")),
+        "rating_key": str(_safe_attr(playlist, "ratingKey", "")),
+    }
+
+
+def format_collection(collection: Any) -> dict:
+    """Format a collection for listing."""
+    return {
+        "title": str(_safe_attr(collection, "title", "")),
+        "item_count": _safe_attr(collection, "childCount"),
+        "rating_key": str(_safe_attr(collection, "ratingKey", "")),
+    }

mcp_plex_server-0.1.3/src/plex_mcp/server.py

@@ -0,0 +1,231 @@
+"""MCP server with Plex tools for media discovery, search, and library management."""
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import PlexClient, PlexError
+
+mcp = FastMCP("mcp-plex")
+
+_client: PlexClient | None = None
+
+
+def _get_client() -> PlexClient:
+    global _client
+    if _client is None:
+        _client = PlexClient()
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def search_media(query: str, media_type: str = "", limit: int = 20) -> str:
+    """Search for media across all Plex libraries.
+
+    Searches movies, shows, music, and other media by title.
+
+    Optional media_type filter: "movie", "show", "episode", "artist",
+    "album", "track".
+
+    Returns titles, years, ratings, and rating keys for further lookup.
+    """
+    try:
+        results = _get_client().search_media(query, media_type, limit)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_recently_added(limit: int = 20, library_name: str = "") -> str:
+    """Get recently added media from Plex.
+
+    Returns the most recently added items across all libraries, or
+    filtered to a specific library by name (e.g. "Movies", "TV Shows").
+    """
+    try:
+        results = _get_client().get_recently_added(limit, library_name)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_on_deck(limit: int = 10) -> str:
+    """Get the "On Deck" continue-watching list from Plex.
+
+    Returns items that are partially watched or next episodes in a series.
+    """
+    try:
+        results = _get_client().get_on_deck(limit)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Library Browsing
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_libraries() -> str:
+    """List all library sections on the Plex server.
+
+    Returns library names, types (movie, show, artist), item counts, and
+    last updated timestamps.
+    """
+    try:
+        results = _get_client().get_libraries()
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_library_contents(
+    library_name: str, sort: str = "titleSort", limit: int = 50
+) -> str:
+    """Browse the contents of a specific Plex library.
+
+    library_name must match exactly (e.g. "Movies", "TV Shows").
+    Use get_libraries to see available names.
+
+    Sort options: "titleSort" (default), "addedAt:desc", "year:desc",
+    "rating:desc", "audienceRating:desc".
+    """
+    try:
+        results = _get_client().get_library_contents(library_name, sort, limit)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_media_details(rating_key: str) -> str:
+    """Get detailed information about a specific media item.
+
+    Use the rating_key from search or browse results. Returns full
+    details including summary, genres, cast, directors, and ratings.
+    """
+    try:
+        result = _get_client().get_media_details(rating_key)
+        return json.dumps(result, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_library_stats(library_name: str = "") -> str:
+    """Get statistics for Plex libraries.
+
+    Without library_name: returns item counts for all libraries.
+    With library_name: returns detailed stats for that library.
+    """
+    try:
+        result = _get_client().get_library_stats(library_name)
+        return json.dumps(result, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Shows
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_seasons(rating_key: str) -> str:
+    """Get the seasons of a TV show.
+
+    Provide the rating_key of a show (from search or browse). Returns
+    season numbers, episode counts, and rating keys.
+    """
+    try:
+        results = _get_client().get_seasons(rating_key)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_episodes(rating_key: str, season_number: int = 0) -> str:
+    """Get episodes for a TV show or season.
+
+    Provide the rating_key of a show. Optionally filter by season_number
+    (0 = all seasons). Returns episode titles, numbers, and durations.
+    """
+    try:
+        results = _get_client().get_episodes(rating_key, season_number)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Collections & Playlists
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def get_collections(library_name: str) -> str:
+    """List collections in a Plex library.
+
+    Returns collection names, item counts, and rating keys.
+    """
+    try:
+        results = _get_client().get_collections(library_name)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_playlists() -> str:
+    """List all playlists on the Plex server.
+
+    Returns playlist names, types, item counts, and durations.
+    """
+    try:
+        results = _get_client().get_playlists()
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+@mcp.tool()
+def get_playlist_items(rating_key: str) -> str:
+    """Get the items in a Plex playlist.
+
+    Provide the rating_key of a playlist. Returns the media items
+    contained in the playlist.
+    """
+    try:
+        results = _get_client().get_playlist_items(rating_key)
+        return json.dumps(results, indent=2)
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Management
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def scan_library(library_name: str) -> str:
+    """Trigger a library scan on the Plex server.
+
+    This refreshes the library to pick up new or changed media files.
+    The scan runs in the background on the server.
+    """
+    try:
+        result = _get_client().scan_library(library_name)
+        return result
+    except (PlexError, ValueError) as e:
+        return f"Error: {e}"

mcp_plex_server-0.1.3/src/plex_mcp/validation.py

@@ -0,0 +1,14 @@
+"""Input validation helpers for Plex rating keys and pagination parameters."""
+
+
+def validate_rating_key(value: str) -> str:
+    """Validate a Plex rating key (numeric string)."""
+    value = value.strip()
+    if not value.isdigit():
+        raise ValueError(f"Invalid rating key: '{value}'. Expected a numeric string.")
+    return value
+
+
+def validate_limit(value: int, max_val: int = 50) -> int:
+    """Clamp a limit parameter to the range [1, max_val]."""
+    return max(1, min(value, max_val))