Plex

Fornece aos assistentes de IA acesso abrangente a um Plex Media Server.

Documentação

Servidor MCP Plex

Um servidor Model Context Protocol (MCP) que fornece aos assistentes de IA acesso abrangente ao seu Plex Media Server, Sonarr, Radarr e Trakt.tv — tudo a partir de um único servidor unificado.

O que é isto?

Este servidor MCP transforma o seu Plex Media Server em um banco de dados consultável por IA. Pergunte ao seu assistente de IA coisas como:

"Quais filmes assisti recentemente?"
"Mostre minhas estatísticas de visualização do último mês"
"Qual é o conteúdo mais popular no meu servidor?"
"Encontre filmes de ação na minha biblioteca"
"O que está na minha lista de continuar assistindo?"
"Adicione aquela nova série ao Sonarr"
"O que está na minha fila de downloads?"
"Sincronize meu histórico de visualizações com o Trakt"
"Recomende alguns filmes que eu ainda não vi"

Recursos

46 ferramentas prontas para uso (58 com operações de escrita habilitadas):

Gerenciamento da Biblioteca Plex — Navegue por bibliotecas, pesquise mídias, obtenha metadados detalhados, liste playlists e lista de assistir
Analíticas Estilo Tautulli — Estatísticas de visualização, atividade de usuários, conteúdo popular, histórico de visualizações
Recomendações Personalizadas — Sugestões de filmes com tecnologia de IA baseadas no seu histórico de visualizações, gêneros, diretores e atores. Suporta perfis por usuário para servidores Plex multiusuário.
Integração Sonarr/Radarr — Navegue, pesquise, adicione séries/filmes, visualize filas, acione downloads
Sincronização Trakt.tv — Autenticação OAuth, sincronização de histórico de visualizações, estatísticas aprimoradas, scrobbling. Quando configurado, os dados do Trakt enriquecem as recomendações capturando filmes assistidos fora do Plex.
Operações de Escrita (opt-in) — Crie/edite playlists, atualize metadados, gerencie a lista de assistir, avalie mídias e marque mídias como assistidas ou não assistidas

Um servidor, todas as ferramentas. As credenciais do Trakt e Sonarr/Radarr são opcionais — ferramentas que precisam delas retornam uma mensagem de configuração útil se a chave estiver ausente. Você não precisa configurar tudo antecipadamente.

Início Rápido

Pré-requisitos

Node.js 20+
Plex Media Server (qualquer versão recente)
Token Plex (Como obter seu token)
Cliente compatível com MCP (Claude Desktop, etc.)

Instalação

# Clone the repository
git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Ou instale diretamente do npm:

npx plex-mcp-server

Configuração

Obtenha seu token Plex (veja instruções abaixo)
Configure seu cliente MCP (ex.: Claude Desktop):

{
  "mcpServers": {
    "plex": {
      "command": "node",
      "args": ["/path/to/plex-mcp-server/build/plex-mcp-server.js"],
      "env": {
        "PLEX_URL": "http://localhost:32400",
        "PLEX_TOKEN": "your_plex_token_here",

        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "optional_sonarr_api_key",

        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "optional_radarr_api_key",

        "TRAKT_CLIENT_ID": "optional_trakt_client_id",
        "TRAKT_CLIENT_SECRET": "optional_trakt_client_secret"
      }
    }
  }
}

Apenas PLEX_TOKEN é obrigatório. Todas as outras credenciais são opcionais — ferramentas para serviços não configurados retornam uma mensagem de erro clara explicando como configurá-los, em vez de travar o servidor.

Chaves de API Sonarr/Radarr podem ser encontradas em Configurações > Geral > Chave de API na interface web de cada aplicativo.

Configuração do Trakt.tv requer um aplicativo OAuth Trakt. Crie um com URI de redirecionamento urn:ietf:wg:oauth:2.0:oob, depois adicione o Client ID e o Secret à sua configuração. Quando o servidor estiver em execução, peça ao seu assistente de IA para "autenticar com o Trakt" — ele o guiará pelo fluxo OAuth. Veja o guia de configuração do Trakt para instruções detalhadas.

Respostas Compactas (opcional)

As ferramentas respondem com JSON por padrão. Definir PLEX_OUTPUT_FORMAT=toon as alterna para TOON, que escreve um array de registros uma vez como cabeçalho e depois como linhas, em vez de repetir cada nome de campo em cada registro:

results[3]{ratingKey,title,year}:
  1001,Arrival,2016
  1002,Sicario,2015
  1003,Dune,2021

Esses são os mesmos dados que seu assistente receberia, em menos tokens — cerca de um terço a menos em uma variedade de respostas de ferramentas, e 40–60% menos nas respostas em formato de lista como search_media, get_library_items e radarr_get_movies. A economia só vale a pena em listas longas, então cada resposta é emitida como TOON apenas quando TOON é realmente mais curto, e como JSON caso contrário; habilitar isso não pode tornar uma resposta maior do que é hoje.

"env": {
  "PLEX_TOKEN": "your_plex_token_here",
  "PLEX_OUTPUT_FORMAT": "toon"
}

Deixe a variável não definida — o padrão — e as respostas serão byte a byte o JSON de sempre.

Migrando da v1.0.x?

Na v1.0.x havia três binários de servidor separados (build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js). Na v1.1.0+ eles são substituídos por um único binário unificado: build/plex-mcp-server.js.

Os binários antigos ainda funcionam, mas emitem um aviso de depreciação. Atualize sua configuração MCP para apontar para build/plex-mcp-server.js e remova quaisquer entradas de servidor duplicadas.

Veja o guia de migração para detalhes completos.

Uso

Uma vez configurado, você pode perguntar ao seu assistente de IA:

"What movies did I watch last week?"
"Show me my most popular TV shows this month"
"Give me viewing statistics for the past 30 days"
"Search for Night of the Living Dead in my library"
"What's on my continue watching list?"
"List all my Plex libraries"
"Add that new show to Sonarr"
"What's in my Radarr download queue?"
"Sync my Plex history to Trakt"

Fluxos de Trabalho Recomendados

Sincronizar histórico de visualizações do Plex com o Trakt:

Configure as credenciais do Trakt (veja acima)
Pergunte: "Autenticar com o Trakt" — siga o fluxo OAuth
Pergunte: "Fazer uma sincronização de teste do meu histórico do Plex para o Trakt" — visualize o que seria sincronizado
Pergunte: "Sincronizar meu histórico de visualizações do Plex com o Trakt" — execute a sincronização real

Encontrar e adicionar novo conteúdo:

Pergunte: "Pesquisar no Sonarr por The Beverly Hillbillies" — encontre o ID TVDB
Pergunte: "Adicionar The Beverly Hillbillies ao Sonarr" — ele detecta automaticamente perfis de qualidade e pastas raiz
Pergunte: "O que está na minha fila de downloads do Sonarr?" — monitore o progresso

Obter recomendações personalizadas:

Pergunte: "Recomende alguns filmes da minha biblioteca"
O mecanismo analisa seu histórico de visualizações — gêneros, diretores, atores, avaliações
Pontua cada filme não assistido e retorna as melhores correspondências com motivos
Para servidores multiusuário, especifique o usuário: "Recomende filmes para Titus"
Se o Trakt estiver configurado, ele usa automaticamente seu histórico do Trakt também — capturando filmes que você assistiu fora do Plex (outras plataformas, antes da configuração do rastreamento)

Análises de visualização entre plataformas:

Pergunte: "Mostre minhas estatísticas de visualização do Plex nos últimos 30 dias"
Pergunte: "Quais são minhas estatísticas do Trakt?" — veja estatísticas vitalícias (filmes assistidos, horas, marcos)
Pergunte: "Quais são meus filmes mais populares este mês?"

Funções Disponíveis

46 ferramentas prontas para uso (58 com operações de escrita habilitadas).

Ferramentas Plex (20 ferramentas)

Função	Descrição
`get_libraries`	Listar todas as bibliotecas Plex
`get_library_items`	Listar itens em uma biblioteca com paginação
`export_library`	Exportar uma biblioteca completa para JSON (sob `./exports`)
`search_media`	Pesquisar mídia globalmente ou dentro de uma biblioteca
`get_recently_added`	Conteúdo adicionado recentemente
`get_on_deck`	Lista de continuar assistindo
`get_media_details`	Informações detalhadas da mídia
`get_editable_fields`	Mostrar campos editáveis e tags disponíveis para um item
`get_playlists`	Listar todas as playlists do Plex
`get_playlist_items`	Listar itens em uma playlist
`get_watchlist`	Obter a lista de assistir da conta atual do Plex Discover
`get_recently_watched`	Conteúdo assistido recentemente
`get_watch_history`	Sessões de visualização detalhadas
`get_fully_watched`	Filmes/séries totalmente assistidos
`get_watch_stats`	Estatísticas abrangentes de visualização
`get_user_stats`	Estatísticas de atividade de usuários
`get_library_stats`	Métricas de uso da biblioteca
`get_popular_content`	Análise de conteúdo mais popular
`get_recommendations`	Recomendações personalizadas de filmes baseadas no seu histórico de visualizações
`get_active_sessions`	Streams Plex ativos no momento — quem está assistindo o quê, estado do player, transcodificação

Operações de Escrita (12 ferramentas, opt-in)

Defina PLEX_ENABLE_MUTATIVE_OPS=true para habilitar estas ferramentas. Elas permitem que seu assistente de IA faça alterações no seu servidor Plex. Use com cuidado — embora testemos estas ferramentas, não há garantias. Revise as alterações que seu assistente propõe antes de confirmar.

Função	Descrição
`update_metadata`	Atualizar campos de metadados e tags editáveis para um item de mídia
`update_metadata_from_json`	Aplicar um payload JSON de metadados usando mapeamento de campos de melhor esforço
`create_playlist`	Criar uma nova playlist inteligente ou estática
`add_to_playlist`	Adicionar um item de mídia a uma playlist
`remove_from_playlist`	Remover um item de uma playlist
`clear_playlist`	Visualizar e opcionalmente limpar todos os itens de uma playlist (`confirm=true`)
`delete_playlist`	Excluir uma playlist sem excluir a mídia subjacente
`add_to_watchlist`	Adicionar um filme ou série local correspondente à lista de assistir da conta
`remove_from_watchlist`	Remover um item da lista de assistir da conta pelo GUID Plex global ou chave de classificação local
`rate_media`	Definir a avaliação do usuário para um item de mídia de 0 a 10
`mark_watched`	Marcar um item de mídia como assistido
`mark_unwatched`	Marcar um item de mídia como não assistido

Ferramentas Sonarr (8 ferramentas)

Função	Descrição
`sonarr_get_series`	Listar séries com filtro de título opcional
`sonarr_search`	Pesquisar novas séries no TheTVDB
`sonarr_add_series`	Adicionar série por ID TVDB
`sonarr_get_missing`	Episódios ausentes/desejados
`sonarr_get_queue`	Fila de downloads
`sonarr_get_calendar`	Próximos episódios
`sonarr_get_profiles`	Perfis de qualidade e pastas raiz
`sonarr_trigger_search`	Acionar busca de episódios ausentes

Ferramentas Radarr (8 ferramentas)

Função	Descrição
`radarr_get_movies`	Listar filmes com filtro de título opcional
`radarr_search`	Pesquisar novos filmes no TMDB
`radarr_add_movie`	Adicionar filme por ID TMDB
`radarr_get_missing`	Filmes ausentes/desejados
`radarr_get_queue`	Fila de downloads
`radarr_get_calendar`	Próximos filmes
`radarr_get_profiles`	Perfis de qualidade e pastas raiz
`radarr_trigger_search`	Acionar busca de filmes ausentes

Ferramentas Entre Serviços (1 ferramenta)

Função	Descrição
`arr_get_status`	Verificar status de conexão Sonarr/Radarr

Ferramentas Trakt (9 ferramentas)

Função	Descrição
`trakt_authenticate`	Iniciar fluxo OAuth do Trakt.tv
`trakt_complete_auth`	Completar autenticação
`trakt_get_auth_status`	Verificar status de autenticação
`trakt_sync_to_trakt`	Sincronizar histórico do Plex com o Trakt
`trakt_sync_from_trakt`	Obter dados do Trakt para comparação
`trakt_get_user_stats`	Estatísticas aprimoradas do Trakt
`trakt_search`	Pesquisar banco de dados do Trakt
`trakt_start_scrobbling`	Scrobbling em tempo real
`trakt_get_sync_status`	Verificar status da operação de sincronização

Obtendo Seu Token Plex

Abra o Aplicativo Web Plex no seu navegador
Navegue até Configurações > Conta > Privacidade
Clique em "Mostrar Avançado" na parte inferior
Copie seu Token Plex

Método alternativo:

Visite: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account
Procure pelo campo "Token Plex"

Estrutura do Projeto

plex-mcp-server/
├── src/
│   ├── plex-mcp-server.ts    # Unified server entry point (44+ tools)
│   ├── index.ts               # Deprecated shim → plex-mcp-server
│   ├── plex-arr-server.ts     # Deprecated shim → plex-mcp-server
│   ├── plex-trakt-server.ts   # Deprecated shim → plex-mcp-server
│   ├── plex/                  # Shared Plex module
│   │   ├── client.ts          #   Plex API client
│   │   ├── tools.ts           #   Plex tool implementations
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── arr/                   # Sonarr/Radarr module
│   │   ├── client.ts          #   Base ArrClient + Sonarr/Radarr subclasses
│   │   ├── mcp-functions.ts   #   Tool implementations (17 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   ├── tool-schemas.ts    #   MCP tool schema definitions
│   │   ├── constants.ts       #   Configuration defaults
│   │   └── types.ts           #   TypeScript type definitions
│   ├── trakt/                 # Trakt.tv module
│   │   ├── client.ts          #   Trakt API client + OAuth
│   │   ├── sync.ts            #   Plex-to-Trakt sync engine
│   │   ├── mapper.ts          #   Plex-to-Trakt data mapping
│   │   ├── mcp-functions.ts   #   Tool implementations (9 tools)
│   │   ├── tool-registry.ts   #   Map-based tool dispatch
│   │   └── tool-schemas.ts    #   MCP tool schema definitions
│   ├── shared/                # Shared utilities
│   │   └── utils.ts           #   truncate, sleep, chunkArray
│   └── __tests__/             # Test suite (94 tests)
├── build/                     # Compiled JavaScript output
├── docs/                      # Documentation
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example               # Environment variables template
└── README.md

Desenvolvimento

Scripts

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch

Compilando a Partir do Código Fonte

git clone https://github.com/niavasha/plex-mcp-server.git
cd plex-mcp-server
npm install
npm run dev

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças importantes, abra uma issue primeiro para discutir o que você gostaria de alterar.

Contribuidores mesclados são creditados em CONTRIBUTORS.md. Por favor, use Conventional Commits — releases e o changelog são gerados a partir deles, veja docs/RELEASING.md.

Diretrizes de Desenvolvimento

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Solução de Problemas

Problemas Comuns

Conexão recusada:

Verifique se seu servidor Plex está em execução
Verifique o PLEX_URL na sua configuração de ambiente
Garanta que a porta (geralmente 32400) esteja correta Host inacessível (EHOSTUNREACH / erros de conexão) no macOS:
No macOS Sequoia, Sonoma ou versões posteriores, conexões para endereços IP locais (como 10.0.0.10 ou 192.168.1.50) podem ser bloqueadas pelas configurações de Privacidade da Rede Local.
Solução alternativa 1: Tente conectar usando o nome de host local (ex.: plex.local ou o nome do seu servidor Plex) em vez do endereço IP direto. Alternativamente, use um domínio *.plex.direct do Plex.
Solução alternativa 2: Vá para Ajustes do Sistema -> Privacidade e Segurança -> Rede Local no seu Mac e garanta que o cliente MCP (ex.: Claude Desktop, Terminal ou VS Code) esteja habilitado e tenha permissão para acessar a rede local.

Erros de autenticação:

Verifique se o seu token do Plex está correto
Confira as permissões do token nas configurações do Plex
Garanta que o token não expirou

Respostas vazias:

Alguns recursos exigem o Plex Pass
Verifique se suas bibliotecas estão acessíveis
Confirme se a mídia foi escaneada e está disponível

Problemas de conexão com Sonarr/Radarr:

Verifique se o Sonarr/Radarr está em execução e acessível a partir do host do servidor MCP
Confirme se a chave da API está correta (Configurações > Geral > Chave da API)
O Sonarr usa a API v3 em /api/v3/ — garanta que sua URL não inclua um caminho adicional
Para bibliotecas grandes do Radarr (20 mil+ filmes), a chamada inicial de radarr_get_movies pode levar até 30 segundos

Problemas de autenticação do Trakt:

Garanta que TRAKT_CLIENT_ID e TRAKT_CLIENT_SECRET estejam ambos definidos
Use a ferramenta trakt_authenticate para iniciar o fluxo OAuth
Complete a autenticação com trakt_complete_auth usando o código do Trakt

Problemas com o cliente MCP:

Garanta que o caminho esteja definido para build/plex-mcp-server.js (o servidor unificado)
Verifique se o Node.js está no PATH do seu sistema
Confirme se as variáveis de ambiente estão definidas na configuração do cliente

Obtendo Ajuda

Abra uma issue
Verifique as discussões existentes
Revise a documentação do MCP

Requisitos

Node.js 20.0.0 ou superior
Plex Media Server (qualquer versão recente)
Acesso à rede entre o servidor MCP e o servidor Plex
Token do Plex válido com as permissões apropriadas

Notas de Segurança

Mantenha seu token do Plex seguro — nunca o envie para o controle de versão
Use variáveis de ambiente para configurações sensíveis
Execute em redes confiáveis — o servidor se comunica diretamente com o Plex
Rotação regular de tokens — considere atualizar os tokens periodicamente
Operações de escrita estão desabilitadas por padrão — habilite apenas se você confiar no julgamento do seu assistente de IA

Licença

Este projeto está licenciado sob a Licença MIT — veja o arquivo LICENSE para detalhes.

Agradecimentos

Todos que contribuíram com código — este projeto não é um esforço solo
Anthropic pelo Model Context Protocol
Plex pelo incrível servidor de mídia
Tautulli pela inspiração em análises
A comunidade de código aberto por várias bibliotecas e ferramentas

Projetos Relacionados

Model Context Protocol — O padrão que este servidor implementa
Claude Desktop — Cliente MCP popular
Tautulli — Monitoramento e análises do Plex
PlexAPI — Biblioteca Python da API do Plex

Feito com amor para a comunidade Plex e IA