-
securityF
license-
qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.
Last updated -
16
Provides comprehensive access to a Plex Media Server, allowing querying of libraries, viewing statistics, user activity tracking, media searching, and content management through natural language interactions.
Plex MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to your Plex Media Server. Query your libraries, get viewing statistics, and manage your media through natural language interactions.
🎬 What is this?
This MCP server transforms your Plex Media Server into an AI-queryable database. Ask your AI assistant questions like:
- "What movies have I watched recently?"
- "Show me my viewing statistics for the past month"
- "What's the most popular content on my server?"
- "Find action movies in my library"
- "What's on my continue watching list?"
✨ Features
📚 Library Management
- Browse all Plex libraries
- Search across movies, TV shows, music, and more
- Get detailed metadata for any media item
📊 Tautulli-Style Analytics
- Comprehensive viewing statistics
- User activity tracking
- Popular content analysis
- Watch history with progress tracking
- Library usage metrics
🎯 Smart Querying
- Recently watched content
- Fully watched movies/shows
- Continue watching (On Deck)
- Recently added media
🚀 Quick Start
Prerequisites
- Node.js 18+
- Plex Media Server (any recent version)
- Plex Token (How to get your token)
- MCP-compatible client (Claude Desktop, etc.)
Installation
Configuration
- Get your Plex token (see instructions below)
- Create environment file:
- Configure your MCP client:
Add to your MCP client configuration (e.g., Claude Desktop):
Usage
Once configured, you can ask your AI assistant:
🛠️ Available Functions
| Function | Description | Example Usage |
|---|---|---|
get_libraries | List all Plex libraries | "What libraries do I have?" |
search_media | Search across all media | "Find movies with Tom Hanks" |
get_recently_added | Recently added content | "What's new on my server?" |
get_on_deck | Continue watching list | "What should I continue watching?" |
get_media_details | Detailed media info | "Tell me about The Matrix" |
get_recently_watched | Recently watched content | "What did I watch yesterday?" |
get_fully_watched | Completed content | "Show me all watched movies" |
get_watch_history | Detailed watch sessions | "Show my viewing history" |
get_watch_stats | Viewing analytics | "My watching statistics" |
get_user_stats | User activity data | "Who watches the most?" |
get_library_stats | Library information | "Tell me about my movie library" |
get_popular_content | Most popular media | "What's trending on my server?" |
🔑 Getting Your Plex Token
- Open Plex Web App in your browser
- Navigate to Settings → Account → Privacy
- Click "Show Advanced" at the bottom
- Copy your Plex Token
Alternative method:
- Visit:
http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account - Look for the "Plex Token" field
📁 Project Structure
🔧 Development
Scripts
Building from Source
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Guidelines
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
🐛 Troubleshooting
Common Issues
Connection refused:
- Verify your Plex server is running
- Check the
PLEX_URLin your.envfile - Ensure the port (usually 32400) is correct
Authentication errors:
- Verify your Plex token is correct
- Check token permissions in Plex settings
- Ensure token hasn't expired
Empty responses:
- Some features require Plex Pass
- Check if your libraries are accessible
- Verify media has been scanned and is available
MCP client issues:
- Ensure the path to
build/index.jsis correct - Check that Node.js is in your system PATH
- Verify environment variables are set in client config
Getting Help
- 📝 Open an issue
- 💬 Check existing discussions
- 📖 Review the MCP documentation
📋 Requirements
- Node.js 18.0.0 or higher
- Plex Media Server (any recent version)
- Network access between MCP server and Plex server
- Valid Plex token with appropriate permissions
🔒 Security Notes
- Keep your Plex token secure - never commit it to version control
- Use environment variables for sensitive configuration
- Run on trusted networks - the server communicates directly with Plex
- Regular token rotation - consider refreshing tokens periodically
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Anthropic for the Model Context Protocol
- Plex for the amazing media server
- Tautulli for analytics inspiration
- The open-source community for various libraries and tools
🔗 Related Projects
- Model Context Protocol - The standard this server implements
- Claude Desktop - Popular MCP client
- Tautulli - Plex monitoring and analytics
- PlexAPI - Python Plex API library
Built with ❤️ for the Plex and AI community
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol server that enables AI assistants to query and manage Plex Media Server content through natural language, providing library access, viewing statistics, and media management capabilities.
Related MCP Servers
- -securityFlicense-qualityA comprehensive Model Context Protocol server that bridges LLMs with self-hosted media services, enabling natural language control of TV shows, movies, downloads, and notifications while maintaining traditional API access.Last updated -
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.Last updated -98MIT License
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -71