Plex MCP 서버

AI 어시스턴트가 Plex 미디어 서버, Sonarr, Radarr 및 Trakt.tv에 포괄적으로 액세스할 수 있도록 지원하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 모든 기능을 단일 통합 서버에서 사용할 수 있습니다.

이것은 무엇인가요?

이 MCP 서버는 Plex 미디어 서버를 AI가 쿼리할 수 있는 데이터베이스로 변환합니다. AI 어시스턴트에게 다음과 같이 질문해 보세요:

• "최근에 본 영화가 뭐야?"

• "지난달 시청 통계를 보여줘"

• "내 서버에서 가장 인기 있는 콘텐츠는 뭐야?"

• "내 라이브러리에서 액션 영화를 찾아줘"

• "계속 보기 목록에 뭐가 있지?"

• "그 새 프로그램을 Sonarr에 추가해줘"

• "다운로드 대기열에 뭐가 있지?"

• "내 시청 기록을 Trakt에 동기화해줘"

• "내가 보지 않은 영화를 추천해줘"

Related MCP server: YARR Media Stack MCP Server

기능

기본적으로 45개의 도구를 제공하며(쓰기 작업 활성화 시 54개):

• Plex 라이브러리 관리 — 라이브러리 탐색, 미디어 검색, 상세 메타데이터 확인, 재생 목록 및 관심 목록 나열

• Tautulli 스타일 분석 — 시청 통계, 사용자 활동, 인기 콘텐츠, 시청 기록

• 개인 맞춤형 추천 — 시청 기록, 장르, 감독, 배우를 기반으로 한 AI 영화 추천. 다중 사용자 Plex 서버를 위한 사용자별 프로필 지원.

• Sonarr/Radarr 통합 — 시리즈/영화 탐색, 검색, 추가, 대기열 확인, 다운로드 트리거

• Trakt.tv 동기화 — OAuth 인증, 시청 기록 동기화, 향상된 통계, 스크로블링. 설정 시 Trakt 데이터가 Plex 외부에서 시청한 영화를 포착하여 추천 기능을 강화합니다.

• 쓰기 작업 (선택 사항) — 재생 목록 생성/편집, 메타데이터 업데이트, 관심 목록 관리

하나의 서버, 모든 도구. Trakt 및 Sonarr/Radarr 자격 증명은 선택 사항입니다. 필요한 도구는 키가 누락된 경우 유용한 설정 메시지를 반환합니다. 모든 것을 미리 구성할 필요는 없습니다.

빠른 시작

사전 요구 사항

• Node.js 20 이상

• Plex 미디어 서버 (최신 버전)

• Plex 토큰 (토큰을 얻는 방법)

• MCP 호환 클라이언트 (Claude Desktop 등)

설치

# 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

또는 npm에서 직접 설치:

npx plex-mcp-server

구성

1. Plex 토큰 가져오기 (아래 지침 참조)

2. MCP 클라이언트 구성 (예: 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"
      }
    }
  }
}

PLEX_TOKEN만 필수입니다. 다른 모든 자격 증명은 선택 사항입니다. 구성되지 않은 서비스용 도구는 서버를 중단시키는 대신 설정 방법을 설명하는 명확한 오류 메시지를 반환합니다.

Sonarr/Radarr API 키는 각 앱의 웹 UI에서 설정 > 일반 > API 키를 통해 찾을 수 있습니다.

Trakt.tv 설정은 Trakt OAuth 애플리케이션이 필요합니다. 리디렉션 URI를 urn:ietf:wg:oauth:2.0:oob로 설정하여 생성한 후, 클라이언트 ID와 시크릿을 구성에 추가하세요. 서버가 실행되면 AI 어시스턴트에게 "Trakt로 인증"하라고 요청하면 OAuth 흐름을 안내해 줍니다. 자세한 지침은 Trakt 설정 가이드를 참조하세요.

v1.0.x에는 세 개의 별도 서버 바이너리(build/index.js, build/plex-trakt-server.js, build/plex-arr-server.js)가 있었습니다. v1.1.0 이상에서는 단일 통합 바이너리인 build/plex-mcp-server.js로 대체되었습니다.

이전 바이너리도 작동하지만 더 이상 사용되지 않는다는 경고가 표시됩니다. MCP 구성을 build/plex-mcp-server.js를 가리키도록 업데이트하고 중복된 서버 항목을 제거하세요.

자세한 내용은 마이그레이션 가이드를 참조하세요.

사용법

구성 후 AI 어시스턴트에게 다음과 같이 요청할 수 있습니다:

"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"

권장 워크플로우

Plex 시청 기록을 Trakt에 동기화:

1. Trakt 자격 증명 설정 (위 참조)

2. 요청: "Trakt로 인증해줘" — OAuth 흐름을 따름

3. 요청: "내 Plex 기록을 Trakt에 동기화하는 테스트를 실행해줘" — 동기화될 내용 미리보기

4. 요청: "내 Plex 시청 기록을 Trakt에 동기화해줘" — 실제 동기화 실행

새 콘텐츠 찾기 및 추가:

1. 요청: "Sonarr에서 The Beverly Hillbillies를 검색해줘" — TVDB ID 찾기

2. 요청: "The Beverly Hillbillies를 Sonarr에 추가해줘" — 품질 프로필과 루트 폴더를 자동으로 감지

3. 요청: "Sonarr 다운로드 대기열에 뭐가 있지?" — 진행 상황 모니터링

개인 맞춤형 추천 받기:

1. 요청: "내 라이브러리에서 영화를 추천해줘"

2. 엔진이 시청 기록(장르, 감독, 배우, 평점)을 분석

3. 보지 않은 모든 영화의 점수를 매기고 이유와 함께 상위 항목을 반환

4. 다중 사용자 서버의 경우 사용자를 지정: "Titus를 위한 영화를 추천해줘"

5. Trakt가 구성된 경우, Plex 외부에서 시청한 영화까지 포함하여 기록을 자동으로 사용

교차 플랫폼 시청 분석:

1. 요청: "지난 30일간의 Plex 시청 통계를 보여줘"

2. 요청: "내 Trakt 통계는 어때?" — 평생 통계(시청한 영화, 시간, 이정표) 확인

3. 요청: "이번 달 가장 인기 있는 영화는 뭐야?"

사용 가능한 기능

Plex 도구 (19개)

쓰기 작업 (9개, 선택 사항)

PLEX_ENABLE_MUTATIVE_OPS=true를 설정하여 이 도구들을 활성화하세요. AI 어시스턴트가 Plex 서버를 변경할 수 있게 합니다. 주의해서 사용하세요. 테스트는 거쳤으나 보장되지는 않습니다. 어시스턴트가 제안하는 변경 사항을 확인하기 전에 검토하세요.

Sonarr 도구 (8개)

Radarr 도구 (8개)

교차 서비스 도구 (1개)

Trakt 도구 (9개)

Plex 토큰 가져오기

1. 브라우저에서 Plex 웹 앱 열기

2. 설정 > 계정 > 개인정보 보호로 이동

3. 하단의 "고급 표시" 클릭

4. Plex 토큰 복사

대체 방법:

• 방문: http://YOUR_PLEX_IP:32400/web/index.html#!/settings/account

• "Plex 토큰" 필드 찾기

프로젝트 구조

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

개발

스크립트

# 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

소스에서 빌드

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

기여

기여를 환영합니다! 자유롭게 Pull Request를 제출해 주세요. 주요 변경 사항의 경우, 먼저 이슈를 열어 변경하고 싶은 내용을 논의해 주세요.

개발 가이드라인

1. 저장소 포크

2. 기능 브랜치 생성 (git checkout -b feature/amazing-feature)

3. 변경 사항 커밋 (git commit -m 'Add amazing feature')

4. 브랜치 푸시 (git push origin feature/amazing-feature)

5. Pull Request 열기

문제 해결

일반적인 문제

연결 거부:

• Plex 서버가 실행 중인지 확인

• 환경 구성에서 PLEX_URL 확인

• 포트(보통 32400)가 올바른지 확인

인증 오류:

• Plex 토큰이 올바른지 확인

• Plex 설정에서 토큰 권한 확인

• 토큰이 만료되지 않았는지 확인

빈 응답:

• 일부 기능은 Plex Pass가 필요함

• 라이브러리에 액세스할 수 있는지 확인

• 미디어가 스캔되었고 사용 가능한지 확인

Sonarr/Radarr 연결 문제:

• Sonarr/Radarr가 실행 중이고 MCP 서버 호스트에서 액세스 가능한지 확인

• API 키가 올바른지 확인 (설정 > 일반 > API 키)

• Sonarr은 /api/v3/에서 API v3를 사용함 — URL에 후행 경로가 포함되지 않았는지 확인

• 대규모 Radarr 라이브러리(2만 개 이상의 영화)의 경우, 초기 radarr_get_movies 호출에 최대 30초가 걸릴 수 있음

Trakt 인증 문제:

• TRAKT_CLIENT_ID와 TRAKT_CLIENT_SECRET이 모두 설정되었는지 확인

• trakt_authenticate 도구를 사용하여 OAuth 흐름 시작

• Trakt에서 받은 코드로 trakt_complete_auth를 사용하여 인증 완료

MCP 클라이언트 문제:

• 경로가 build/plex-mcp-server.js(통합 서버)로 설정되었는지 확인

• Node.js가 시스템 PATH에 있는지 확인

• 클라이언트 구성에서