yt-playlist-organizer-mcp

YouTube Data API v3를 통해 YouTube 재생목록을 구성하기 위한 MCP 서버입니다.

이 서버는 오직 한 가지만 수행합니다: 재생목록과 재생목록 항목을 생성, 조회, 수정, 삭제합니다. 비디오, 채널, 자막, 댓글, 구독 또는 다른 YouTube Data API 리소스에는 접근하지 않습니다.

공식 @modelcontextprotocol/sdk와 YouTube Data API v3 REST 엔드포인트로 구축되었습니다 (무거운 googleapis 의존성 없음).

도구

이 서버가 수행하는 모든 것입니다. 다른 도구는 없습니다.

재생목록 (/playlists)

재생목록 항목 (/playlistItems)

어떤 자격 증명이 구성되어 있는지 확인하는 auth_status도 있습니다.

Related MCP server: youtube-mcp

구성

이 서버는 /playlists 및 /playlistItems 엔드포인트만 호출합니다. 나머지 YouTube Data API는 범위에 포함되지 않습니다.

서버는 두 개의 환경 변수를 읽습니다:

.env.example을 참조하세요.

• 읽기(..._list)는 API 키(또는 액세스 토큰)만으로 작동합니다.

• 쓰기(insert/update/delete) 및 mine=true는 youtube, youtube.force-ssl 또는 youtubepartner 범위가 있는 OAuth2 액세스 토큰이 필요합니다.

OAuth2 자격 증명 가져오기

1. Google Cloud Console에서 프로젝트를 생성합니다.

2. YouTube Data API v3를 사용 설정합니다.

3. OAuth2 클라이언트 ID(데스크톱 앱)를 생성하고 JSON을 다운로드합니다.

4. 자격 증명을 액세스 토큰으로 교환합니다 (예: Python의 google-auth-oauthlib 또는 로컬 OAuth 흐름 서비스 사용). YOUTUBE_ACCESS_TOKEN=<token>을 설정합니다.

5. (선택 사항) 더 간단한 읽기 전용 사용을 위해 API 키를 생성합니다.

Nix

NixOS 친화적입니다. flake와 shell.nix가 모두 제공됩니다.

# Enter the dev shell (node + typescript toolchain)
nix develop

# or, non-flake:
nix-shell

빌드

npm install        # install node deps (zod + MCP SDK)
npm run build      # emits dist/
npm run typecheck  # tsc --noEmit

로컬에서 실행

# Reads only (API key):
YOUTUBE_API_KEY=... node dist/index.js

# Reads + writes/mine (OAuth access token):
YOUTUBE_ACCESS_TOKEN=... node dist/index.js

opencode에 연결

mcp 아래의 ~/.config/opencode/opencode.jsonc에 다음을 추가합니다:

"mcp": {
  "yt-playlist-organizer-mcp": {
    "type": "local",
    "command": ["node", "<path-to-repo>/dist/index.js"],
    "enabled": true,
    "environment": {
      "YOUTUBE_API_KEY": "{file:~/.secrets/yt-api-key}",
      "YOUTUBE_ACCESS_TOKEN": "{file:~/.secrets/yt-access-token}"
    }
  }
}

<path-to-repo>를 복제한 절대 경로로 바꾸거나, npm으로 설치하여 이름으로 실행합니다:

npm install -g .
# then use:  "command": ["yt-playlist-organizer-mcp"]

대신 Nix 셸을 통해 실행하려면 동일한 키를 사용하되 command를 변경합니다:

"command": ["nix", "develop", "<path-to-repo>", "--command", "node", "dist/index.js"],

참고 사항

• 할당량 비용은 공식 API 문서 기준이며 도구별로 명시되어 있습니다.

• part 값은 각 리소스의 유효한 집합에 대해 검증됩니다.

• playlists_list / playlistItems_list는 정확히 하나의 필터 매개변수가 필요합니다. 그렇지 않으면 입력 검증이 호출을 거부합니다.

• 업데이트 도구(playlists_update, playlistItems_update)는 먼저 기존 리소스를 읽고 생략된 필드(예: description, privacyStatus, position, contentDetails)를 지우는 대신 유지합니다. 따라서 각 업데이트는 할당량에서 추가 읽기 비용이 발생합니다.

• startAt/endAt은 초 단위로 제공되며 API로 전송되기 전에 ISO 8601 기간(PT1M30S)으로 변환됩니다.

개발

npm install
npm test         # vitest unit tests
npm run typecheck
npm run build

라이선스

MIT