Plex MCP Server

Um servidor MCP para gerenciar sua biblioteca de mídia Plex com assistentes de IA.

GitHub

Documentação

Servidor Plex MCP

Um servidor Model Context Protocol (MCP) para gerenciamento de mídia Plex, permitindo que assistentes de IA como Claude interajam com sua biblioteca Plex.

Recursos

  • Gerenciamento de Filmes: Pesquise, navegue e analise sua coleção de filmes
  • Estatísticas da Biblioteca: Obtenha insights sobre sua coleção de mídia
  • Pesquisa por Gênero e Diretor: Encontre conteúdo por critérios específicos
  • Adições Recentes: Acompanhe conteúdo recém-adicionado
  • Arquitetura Extensível: Fácil adicionar programas de TV e outros tipos de mídia

Requisitos

  • Python 3.8 ou superior
  • Plex Media Server com API acessível
  • Acesso à rede para seu servidor Plex

Configuração

Configuração Rápida (Recomendado)

# Clone the repository
git clone https://github.com/richarddas/plex_mcp_server.git
cd plex_mcp_server

# Run the setup script (creates venv and installs dependencies)
./setup.sh

# Edit your Plex details
nano .env

# Activate virtual environment and start the server
source venv/bin/activate
python main.py

Configuração Manual

  1. Crie e ative o ambiente virtual:

    python3 -m venv venv
source venv/bin/activate

  2. Instale as dependências:

    pip install --upgrade pip
pip install -r requirements.txt

  3. Configure as variáveis de ambiente:

    cp .env.example .env
nano .env

    Atualize os valores em .env:

    • PLEX_URL: URL do seu servidor Plex (ex.: http://192.168.1.100:32400)
    • PLEX_TOKEN: Seu token de autenticação Plex (Como encontrá-lo)
    • HOST e PORT: Endereço do servidor (os padrões são suficientes para a maioria das configurações)
    • LOG_LEVEL: Nível de detalhamento do log (INFO recomendado)

  4. Execute o servidor:

    python main.py

Uso Diário

Após a configuração inicial, para executar o servidor:

cd plex-mcp-server
source venv/bin/activate  # Activate virtual environment
python main.py            # Start server
# When done: deactivate   # Exit virtual environment

Configuração do Claude Desktop

Adicione ao seu config.json do Claude Desktop:

{
  "globalShortcut": "",
  "mcpServers": {
    "plex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://your-server:8000/sse",
        "--allow-http"
      ]
    }
  }
}

Ferramentas Disponíveis

Ferramentas de Filmes

  • get_library_stats - Estatísticas gerais da biblioteca
  • list_all_movies - Navegue por todos os filmes com paginação
  • search_movies - Pesquise por título
  • search_by_genre - Encontre filmes por gênero
  • search_by_director - Encontre filmes por diretor
  • search_by_year_range - Encontre filmes por intervalo de anos
  • get_all_genres - Liste todos os gêneros disponíveis
  • get_all_directors - Liste todos os diretores
  • get_recent_movies - Filmes adicionados recentemente

Estrutura do Projeto

plex_mcp_server/
├── main.py              # FastAPI server
├── config.py            # Configuration
├── plex_client.py       # Plex connection
├── mcp_handler.py       # MCP message handling
├── tools/
│   ├── movie_tools.py   # Movie-related tools
│   └── tv_tools.py      # TV tools (future)
└── requirements.txt     # Dependencies

Desenvolvimento

Para adicionar novas ferramentas:

  1. Adicione métodos ao arquivo de ferramentas apropriado
  2. Atualize o método get_tool_definitions()
  3. Registre a ferramenta em mcp_handler.py

Licença

Licença MIT