plex-mcp 0.1.0 → 0.2.0

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

package/README.md

@@ -8,6 +8,8 @@ A Model Context Protocol (MCP) server for searching Plex media libraries using C
 - 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
 
@@ -16,19 +18,22 @@ A Model Context Protocol (MCP) server for searching Plex media libraries using C
    npm install
    ```
 
-2. Configure your Plex connection:
-   - Copy `.env.example` to `.env`
+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
      ```
-
-3. Get your Plex token:
-   - Log into your Plex account
-   - Go to Settings > Account > Privacy
-   - Click "Show" next to "Plex Pass Subscription"
-   - Your token will be displayed
+   - Get your Plex token by visiting [Plex Token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/)
 
 ## Claude Desktop Configuration
 
@@ -113,9 +118,76 @@ Run the MCP server standalone:
 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.
+
+4. **Clear Authentication (Optional):**
+   ```
+   Use the clear_auth tool
+   ```
+   This removes stored credentials if needed.
+
+### 2. Static Token Authentication
+
+For automated setups or if you prefer manual token management:
+
+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
+
+**Note:** The OAuth method takes precedence - if both are available, static tokens are used as fallback.
+
 ## MCP Tools
 
-### search_plex
+### Authentication Tools
+
+#### authenticate_plex
+Start the Plex OAuth authentication flow.
+
+**Parameters:** None
+
+**Returns:** Login URL and pin ID for browser authentication.
+
+#### check_auth_status
+Check if OAuth authentication is complete and retrieve the token.
+
+**Parameters:**
+- `pin_id` (string, optional): Specific pin ID to check
+
+**Returns:** Authentication status and success confirmation.
+
+#### clear_auth
+Clear stored authentication credentials.
+
+**Parameters:** None
+
+**Returns:** Confirmation of credential removal.
+
+### Content Tools
+
+#### search_plex
 
 Search for content in your Plex libraries.
 

package/index.js

@@ -7,6 +7,84 @@ const {
   ListToolsRequestSchema,
 } = require("@modelcontextprotocol/sdk/types.js");
 const axios = require('axios');
+const { PlexOauth } = require('plex-oauth');
+
+class PlexAuthManager {
+  constructor() {
+    this.authToken = null;
+    this.plexOauth = null;
+    this.currentPinId = null;
+  }
+
+  async getAuthToken() {
+    // Try static token first
+    const staticToken = process.env.PLEX_TOKEN;
+    if (staticToken) {
+      return staticToken;
+    }
+
+    // Return stored OAuth token if available
+    if (this.authToken) {
+      return this.authToken;
+    }
+
+    throw new Error('No authentication token available. Please authenticate first using the authenticate_plex tool or set PLEX_TOKEN environment variable.');
+  }
+
+  initializeOAuth() {
+    if (this.plexOauth) {
+      return this.plexOauth;
+    }
+
+    const clientInfo = {
+      clientIdentifier: process.env.PLEX_CLIENT_ID || 'plex-mcp-client',
+      product: process.env.PLEX_PRODUCT || 'Plex MCP Server',
+      device: process.env.PLEX_DEVICE || 'MCP Server',
+      version: process.env.PLEX_VERSION || '1.0.0',
+      forwardUrl: process.env.PLEX_REDIRECT_URL || 'https://app.plex.tv/auth#!',
+      platform: process.env.PLEX_PLATFORM || 'Web'
+    };
+
+    this.plexOauth = new PlexOauth(clientInfo);
+    return this.plexOauth;
+  }
+
+  async requestAuthUrl() {
+    const oauth = this.initializeOAuth();
+    try {
+      const [hostedUILink, pinId] = await oauth.requestHostedLoginURL();
+      this.currentPinId = pinId;
+      return { loginUrl: hostedUILink, pinId };
+    } catch (error) {
+      throw new Error(`Failed to request authentication URL: ${error.message}`);
+    }
+  }
+
+  async checkAuthToken(pinId = null) {
+    const oauth = this.initializeOAuth();
+    const pin = pinId || this.currentPinId;
+    
+    if (!pin) {
+      throw new Error('No pin ID available. Please request authentication first.');
+    }
+
+    try {
+      const authToken = await oauth.checkForAuthToken(pin);
+      if (authToken) {
+        this.authToken = authToken;
+        return authToken;
+      }
+      return null;
+    } catch (error) {
+      throw new Error(`Failed to check authentication token: ${error.message}`);
+    }
+  }
+
+  clearAuth() {
+    this.authToken = null;
+    this.currentPinId = null;
+  }
+}
 
 class PlexMCPServer {
   constructor() {
@@ -22,6 +100,7 @@ class PlexMCPServer {
       }
     );
 
+    this.authManager = new PlexAuthManager();
     this.setupToolHandlers();
   }
 
@@ -623,6 +702,38 @@ class PlexMCPServer {
               required: [],
             },
           },
+          {
+            name: "authenticate_plex",
+            description: "Initiate Plex OAuth authentication flow to get user login URL",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "check_auth_status",
+            description: "Check if Plex authentication is complete and retrieve the auth token",
+            inputSchema: {
+              type: "object",
+              properties: {
+                pin_id: {
+                  type: "string",
+                  description: "Optional pin ID to check. If not provided, uses the last requested pin.",
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "clear_auth",
+            description: "Clear stored authentication credentials",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
         ],
       };
     });
@@ -666,12 +777,132 @@ class PlexMCPServer {
           return await this.handleGetLibraryStats(request.params.arguments);
         case "get_listening_stats":
           return await this.handleGetListeningStats(request.params.arguments);
+        case "authenticate_plex":
+          return await this.handleAuthenticatePlex(request.params.arguments);
+        case "check_auth_status":
+          return await this.handleCheckAuthStatus(request.params.arguments);
+        case "clear_auth":
+          return await this.handleClearAuth(request.params.arguments);
         default:
           throw new Error(`Unknown tool: ${request.params.name}`);
       }
     });
   }
 
+  async handleAuthenticatePlex(args) {
+    try {
+      const { loginUrl, pinId } = await this.authManager.requestAuthUrl();
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Plex Authentication Started
+
+**Next Steps:**
+1. Open this URL in your browser: ${loginUrl}
+2. Sign into your Plex account  
+3. After signing in, run the check_auth_status tool to complete authentication
+
+**Pin ID:** ${pinId}
+
+Note: Keep this pin ID if you want to check auth status manually later.`
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text", 
+            text: `❌ Authentication Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
+  async handleCheckAuthStatus(args) {
+    const { pin_id } = args;
+    
+    try {
+      const authToken = await this.authManager.checkAuthToken(pin_id);
+      
+      if (authToken) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ Plex Authentication Successful!
+
+Your authentication token has been stored and will be used for all Plex API requests. You can now use all Plex tools without needing the PLEX_TOKEN environment variable.
+
+**Note:** This token is stored only for this session. For persistent authentication, consider setting the PLEX_TOKEN environment variable.`
+            }
+          ]
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⏳ Authentication Pending
+
+The user has not yet completed the authentication process. Please:
+
+1. Make sure you've visited the login URL from the authenticate_plex tool
+2. Sign into your Plex account in the browser
+3. Try checking the auth status again in a few moments
+
+You can run check_auth_status again to check if authentication is complete.`
+            }
+          ]
+        };
+      }
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Auth Status Check Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
+  async handleClearAuth(args) {
+    try {
+      this.authManager.clearAuth();
+      
+      return {
+        content: [
+          {
+            type: "text",
+            text: `🔄 Authentication Cleared
+
+All stored authentication credentials have been cleared. To use Plex tools again, you'll need to either:
+
+1. Set the PLEX_TOKEN environment variable, or
+2. Run the authenticate_plex tool to sign in again`
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `❌ Clear Auth Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
   async handlePlexSearch(args) {
     const { 
       query, 
@@ -706,11 +937,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const searchUrl = `${plexUrl}/search`;
       const params = {
@@ -891,11 +1118,7 @@ class PlexMCPServer {
   async handleBrowseLibraries(args) {
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const librariesUrl = `${plexUrl}/library/sections`;
       const params = {
@@ -1007,11 +1230,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const libraryUrl = `${plexUrl}/library/sections/${library_id}/all`;
       const params = {
@@ -1133,11 +1352,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       let recentUrl;
       if (library_id) {
@@ -1233,11 +1448,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const historyUrl = `${plexUrl}/status/sessions/history/all`;
       const params = {
@@ -1357,11 +1568,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const onDeckUrl = `${plexUrl}/library/onDeck`;
       const params = {
@@ -1460,11 +1667,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const playlistsUrl = `${plexUrl}/playlists`;
       const params = {
@@ -1512,11 +1715,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // First get playlist info
       const playlistUrl = `${plexUrl}/playlists/${playlist_id}`;
@@ -1730,11 +1929,7 @@ class PlexMCPServer {
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // First get server info to get machine identifier
       const serverResponse = await axios.get(`${plexUrl}/`, {
@@ -1839,11 +2034,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get playlist info before adding items
       const playlistInfoUrl = `${plexUrl}/playlists/${playlist_id}`;
@@ -2000,11 +2191,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get playlist info before removing items
       const playlistInfoUrl = `${plexUrl}/playlists/${playlist_id}`;
@@ -2184,11 +2371,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const deleteUrl = `${plexUrl}/playlists/${playlist_id}`;
       const params = {
@@ -2228,11 +2411,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const statusResults = [];
       
@@ -2675,11 +2854,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       let collectionsUrl;
       if (library_id) {
@@ -2729,11 +2904,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const collectionUrl = `${plexUrl}/library/collections/${collection_id}/children`;
       const params = {
@@ -2832,11 +3003,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       const mediaUrl = `${plexUrl}/library/metadata/${item_key}`;
       const params = {
@@ -3125,11 +3292,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Get library information first
       const librariesResponse = await axios.get(`${plexUrl}/library/sections`, { 
@@ -3480,11 +3643,7 @@ You can try creating the playlist manually in Plex and then use other MCP tools
     
     try {
       const plexUrl = process.env.PLEX_URL || 'http://localhost:32400';
-      const plexToken = process.env.PLEX_TOKEN;
-      
-      if (!plexToken) {
-        throw new Error('PLEX_TOKEN environment variable is required');
-      }
+      const plexToken = await this.authManager.getAuthToken();
 
       // Auto-detect music libraries if not specified
       let musicLibraries = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plex-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A Model Context Protocol (MCP) server that enables Claude to query and manage Plex media libraries.",
   "main": "index.js",
   "bin": {
@@ -41,11 +41,12 @@
   "type": "commonjs",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "axios": "^1.9.0"
+    "axios": "^1.9.0",
+    "plex-oauth": "^1.2.2"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "@types/jest": "^29.5.8",
-    "axios-mock-adapter": "^1.22.0"
+    "@types/jest": "^29.5.14",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^29.7.0"
   }
 }