Plex MCP 서버

Plex Media Server API와 통합되어 영화를 검색하고 재생 목록을 관리하는 Python 기반 MCP 서버입니다. Plex 서버와의 원활한 상호 작용을 위해 PlexAPI 라이브러리를 사용합니다.

스크린샷

Plex MCP 서버가 작동하는 방식에 대한 몇 가지 예는 다음과 같습니다.

1. Plex 라이브러리에서 Director별 영화 찾기

Plex 라이브러리에서 감독 이름을 지정하여 영화를 검색하세요. 예를 들어 "알프레드 히치콕"을 검색하면 라이브러리에 있는 그의 영화 목록이 표시됩니다.

2. 감독의 누락된 영화 찾기

Plex 라이브러리에서 누락된 특정 감독의 영화를 찾아보세요. 이를 통해 컬렉션에서 부족한 부분을 발견할 수 있습니다.

3. Plex 라이브러리에 재생 목록 만들기

검색한 영화를 사용하여 Plex 라이브러리에 새 재생 목록을 만들어 보세요. 이렇게 하면 라이브러리를 효율적으로 정리할 수 있습니다.

설정

필수 조건

Python 3.8 이상
uv 패키지 관리자
API 액세스가 가능한 Plex 미디어 서버

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Plex Media Server 통합을 자동으로 설치하려면:

지엑스피1

수동 설치

이 저장소를 복제하세요:
git clone <repository-url> cd plex-mcp
uv 로 종속성을 설치합니다:
uv venv source .venv/bin/activate uv sync
Plex 서버에 대한 환경 변수를 구성하세요.
- PLEX_TOKEN : Plex 인증 토큰
- PLEX_SERVER_URL : Plex 서버 URL(예: http://192.168.1.100:32400 )

Plex 토큰 찾기

Plex 토큰은 다음과 같은 방법으로 찾을 수 있습니다.

Plex 웹 앱에 로그인하세요
개발자 도구 열기
콘솔 탭에 다음을 붙여넣고 실행합니다.
window.localStorage.getItem('myPlexAccessToken')

Claude와 함께 사용

Claude 앱에 다음 구성을 추가하세요.

{
    "mcpServers": {
        "plex": {
            "command": "uv",
            "args": [
                "--directory",
                "FULL_PATH_TO_PROJECT",
                "run",
                "src/plex_mcp/plex_mcp.py"
            ],
            "env": {
                "PLEX_TOKEN": "YOUR_PLEX_TOKEN",
                "PLEX_SERVER_URL": "YOUR_PLEX_SERVER_URL"
            }
        }
    }
}

사용 가능한 명령

Plex MCP 서버는 다음 명령을 제공합니다.

명령	설명	OpenAPI 참조
`search_movies`	다양한 필터(예: 제목, 감독, 장르)를 사용하여 라이브러리에서 영화를 검색하고, 결과 개수를 제어하는 `limit` 매개변수를 지원합니다.	`/library/sections/{sectionKey}/search`
`get_movie_details`	특정 영화에 대한 자세한 정보를 얻으세요.	`/library/metadata/{ratingKey}`
`get_movie_genres`	특정 영화의 장르를 알아보세요.	`/library/sections/{sectionKey}/genre`
`list_playlists`	Plex 서버에 있는 모든 재생 목록을 나열합니다.	`/playlists`
`get_playlist_items`	특정 재생목록의 아이템을 가져옵니다.	`/playlists/{playlistID}/items`
`create_playlist`	지정된 영화로 새로운 재생목록을 만듭니다.	`/playlists`
`delete_playlist`	Plex 서버에서 재생 목록을 삭제합니다.	`/playlists/{playlistID}`
`add_to_playlist`	기존 재생목록에 영화를 추가합니다.	`/playlists/{playlistID}/items`
`recent_movies`	라이브러리에서 최근에 추가된 영화를 받아보세요.	`/library/recentlyAdded`

테스트 실행

이 프로젝트에는 단위 테스트와 통합 테스트가 모두 포함되어 있습니다. 각 유형의 테스트를 실행하려면 다음 지침을 따르세요.

단위 테스트

단위 테스트는 라이브 Plex 서버가 필요하지 않고 더미 데이터를 사용하여 각 모듈의 기능을 확인합니다.

모든 단위 테스트를 실행하려면:

uv run pytest

통합 테스트

통합 테스트는 .env 파일에 정의된 환경 변수를 사용하여 라이브 Plex 서버에 대해 실행됩니다. 먼저, 프로젝트 루트에 Plex 구성 정보를 포함하는 .env 파일을 만듭니다.

PLEX_SERVER_URL=https://your-plex-server-url:32400
PLEX_TOKEN=yourPlexTokenHere

통합 테스트는 통합 마커로 표시됩니다. 통합 테스트만 실행하려면 다음을 수행하세요.

uv run pytest -m integration

Plex 서버에 연결 문제가 발생하는 경우 통합 테스트를 실행하여 문제 해결에 도움을 받으세요.

코드 스타일 및 규칙

모듈 구조:
가져오기, 로깅 설정, 유틸리티 함수, 클래스 정의, 전역 도우미, 도구 메서드 및 기본 실행( if __name__ == "__main__": 으로 보호됨)에 대해 명확한 섹션 헤더를 사용합니다.
명명:
클래스에는 CamelCase를 사용하고 함수, 변수, 픽스처에는 lower_snake_case를 사용합니다. 테스트에서는 내장 픽스처(예: monkeypatch )를 사용자 정의 픽스처보다 먼저 나열합니다.
문서 및 설명:
모든 모듈, 클래스, 함수에 간결한 docstring을 포함하고 복잡한 논리에 대한 인라인 주석을 추가합니다.
오류 처리 및 로깅:
일관된 오류 메시지(접두사 "ERROR:")와 명시적인 예외 처리를 제공하는 Python의 logging 모듈을 사용합니다.
비동기 패턴:
I/O 바운드 함수를 비동기로 정의하고 asyncio.to_thread() 사용하여 차단 작업을 처리합니다.

Plex MCP Server

Integrations