plex-mcp 0.3.0 → 0.4.0

package/Dockerfile

@@ -0,0 +1,18 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/build/project-config
+# Auto-generated Dockerfile for Plex MCP Server
+FROM node:lts-alpine AS base
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+
+# Copy source
+COPY . .
+
+# Default verify SSL
+ENV PLEX_VERIFY_SSL=true
+
+# Start the MCP server
+USER non-root
+CMD ["node", "index.js"]

package/README.md

@@ -1,85 +1,18 @@
 # Plex MCP Server
+[![smithery badge](https://smithery.ai/badge/@vyb1ng/plex-mcp)](https://smithery.ai/server/@vyb1ng/plex-mcp)
 
-A Model Context Protocol (MCP) server for searching Plex media libraries using Claude.
+Search and manage your Plex media libraries with Claude. Actively developed by Claude and a nerdy human who mostly uses Plex for auditory delights and wanted to see how much could be accomplished without knowing much about what they're doing. Results may vary, but probably in a good way.
 
-## Features
+## Quick Start
 
-- Search movies, TV shows, episodes, music, and other content in your Plex libraries
-- Filter by content type
-- Configurable result limits
-- Rich formatted results with metadata
-- **Direct Plex authentication with OAuth flow**
-- Support for both static tokens and interactive authentication
-
-## Setup
-
-1. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-2. Configure your Plex connection (two options):
-
-   **Option A: Interactive Authentication (Recommended)**
-   - Set your Plex server URL:
-     ```
-     PLEX_URL=http://your-plex-server:32400
-     ```
-   - Use the `authenticate_plex` tool for OAuth login (see Authentication section below)
-
-   **Option B: Static Token**
-   - Set your Plex server URL and token:
-     ```
-     PLEX_URL=http://your-plex-server:32400
-     PLEX_TOKEN=your_plex_token
-     ```
-   - Get your Plex token by visiting [Plex Token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
-
-## Claude Desktop Configuration
-
-### Option 1: Production (Using npx - Recommended)
-
-Add this configuration to your Claude Desktop settings for the stable published version:
-
-```json
-{
-  "mcpServers": {
-    "plex": {
-      "command": "npx",
-      "args": ["plex-mcp"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    }
-  }
-}
-```
-
-### Option 2: Development (Local)
-
-For development with your local code changes, add this configuration:
-
-```json
-{
-  "mcpServers": {
-    "plex-dev": {
-      "command": "node",
-      "args": ["/path/to/your/plex-mcp/index.js"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    }
-  }
-}
+### Install via Smithery (Recommended)
+```bash
+npx -y @smithery/cli install @vyb1ng/plex-mcp --client claude
 ```
 
-Replace `/path/to/your/plex-mcp/` with the actual path to this project directory.
-
-### Running Both Versions
+### Manual Setup for Claude Desktop
 
-You can configure both versions simultaneously by using different server names (`plex` and `plex-dev`):
+Add to your Claude Desktop MCP settings:
 
 ```json
 {
@@ -88,119 +21,72 @@ You can configure both versions simultaneously by using different server names (
       "command": "npx",
       "args": ["plex-mcp"],
       "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
-      }
-    },
-    "plex-dev": {
-      "command": "node",
-      "args": ["/path/to/your/plex-mcp/index.js"],
-      "env": {
-        "PLEX_URL": "http://your-plex-server:32400",
-        "PLEX_TOKEN": "your_plex_token"
+        "PLEX_URL": "http://your-plex-server:32400"
       }
     }
   }
 }
 ```
 
-**Configuration Steps:**
-1. Open Claude Desktop settings (Cmd/Ctrl + ,)
-2. Navigate to the "MCP Servers" tab
-3. Add the configuration above
-4. Update `PLEX_URL` and `PLEX_TOKEN` with your Plex server details
-5. Restart Claude Desktop
-
-## Usage
-
-Run the MCP server standalone:
-```bash
-node index.js
-```
-
 ## Authentication
 
-The Plex MCP server supports two authentication methods:
-
-### 1. Interactive OAuth Authentication (Recommended)
-
-Use the built-in OAuth flow for secure, interactive authentication:
-
-1. **Start Authentication:**
-   ```
-   Use the authenticate_plex tool
-   ```
-   This will provide you with a Plex login URL and pin ID.
-
-2. **Complete Login:**
-   - Open the provided URL in your browser
-   - Sign into your Plex account
-   - Grant access to the MCP application
-
-3. **Check Authentication Status:**
-   ```
-   Use the check_auth_status tool
-   ```
-   This confirms authentication completion and stores your token.
+**Option 1: OAuth (Recommended)**
+- Use the `authenticate_plex` tool to get a login URL
+- Sign in through your browser
 
-4. **Clear Authentication (Optional):**
-   ```
-   Use the clear_auth tool
-   ```
-   This removes stored credentials if needed.
+**Option 2: Static Token**
+- Add `"PLEX_TOKEN": "your_token"` to the env section
+- Get your token from [Plex Support](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
 
-### 2. Static Token Authentication
+**Note:** Replace `your-plex-server:32400` with your actual Plex server address and port.
 
-For automated setups or if you prefer manual token management:
+## What You Can Do
 
-1. Obtain your Plex token from [Plex Support](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
-2. Set the `PLEX_TOKEN` environment variable
-3. All tools will automatically use this token
+**Search & Browse**
+- Search movies, TV shows, music, and other content
+- Browse libraries and collections
+- View recently added content and watch history
 
-**Note:** The OAuth method takes precedence - if both are available, static tokens are used as fallback.
+**Music Discovery**
+- Natural language music discovery ("songs from the 90s", "rock bands I haven't heard")
+- Smart recommendations based on listening patterns
+- Intelligent randomization for variety and surprise
+- Similar artist discovery and genre exploration
 
-## MCP Tools
+**Playlists**
+- Create and manage playlists
+- Add items to existing playlists
+- Browse playlist contents
 
-### Authentication Tools
+**Media Info**
+- Get detailed media information (codecs, bitrates, file sizes)
+- Check watch status and progress
+- View library statistics and listening stats
 
-#### authenticate_plex
-Start the Plex OAuth authentication flow.
+## Status
 
-**Parameters:** None
+**✅ Working:** Search, browse, playlists, media info, library stats, watch history, collections, music discovery
 
-**Returns:** Login URL and pin ID for browser authentication.
+**❌ Disabled:** Smart playlists (filter logic broken)
 
-#### check_auth_status
-Check if OAuth authentication is complete and retrieve the token.
+**🚧 Planned:** Remote server browsing
 
-**Parameters:**
-- `pin_id` (string, optional): Specific pin ID to check
+## Development
 
-**Returns:** Authentication status and success confirmation.
+Want to contribute? Point Claude at your local version:
 
-#### clear_auth
-Clear stored authentication credentials.
-
-**Parameters:** None
-
-**Returns:** Confirmation of credential removal.
-
-### Content Tools
-
-#### search_plex
-
-Search for content in your Plex libraries.
-
-**Parameters:**
-- `query` (string, required): Search query
-- `type` (string, optional): Content type ("movie", "show", "episode", "artist", "album", "track")
-- `limit` (number, optional): Maximum results (default: 10)
-
-**Example:**
 ```json
 {
-  "query": "Star Wars",
-  "type": "movie",
-  "limit": 5
+  "mcpServers": {
+    "plex-dev": {
+      "command": "node",
+      "args": ["/path/to/plex-mcp/index.js"],
+      "env": {
+        "PLEX_URL": "http://your-plex-server:32400"
+      }
+    }
+  }
 }
-```
+```
+
+It works for us. If it doesn't work for you, well we tried. Hit us up, we don't bite. Much.