moviefinder-mcp

TMDB API를 래핑하여 MCP 지원 클라이언트(Claude Desktop, Claude Code 등)가 영화 및 TV 프로그램을 검색하고, 세부 정보를 조회하며, 인기 콘텐츠를 찾고, 추천을 받으며, 스트리밍 위치를 확인할 수 있게 해주는 MCP 서버입니다.

도구

모든 도구는 원시 TMDB 페이로드 대신 요약된 JSON(id, 제목, 연도, 개요, 평점, 포스터 URL 및 도구별 필드)을 반환합니다.

설정

요구 사항: Node 20+.

npm install
cp .env.example .env
# edit .env and paste your TMDB v4 read access token
npm run build
npm start    # runs the compiled server over stdio

TMDB API 키 발급받기

1. https://www.themoviedb.org/에서 TMDB 계정을 만듭니다.

2. https://www.themoviedb.org/settings/api를 엽니다.

3. **API Read Access Token (v4 auth)**을 복사합니다. (v3 API 키가 아닙니다.)

4. .env 파일에 TMDB_API_KEY=... 형식으로 저장합니다.

서버는 이를 Authorization: Bearer <token>으로 전송합니다.

Claude Desktop에 등록

claude_desktop_config.json 파일을 수정합니다(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "moviefinder": {
      "command": "node",
      "args": ["/absolute/path/to/moviefinder-mcp/dist/index.js"],
      "env": {
        "TMDB_API_KEY": "your_v4_read_access_token_here"
      }
    }
  }
}

Claude Desktop을 재시작합니다. 위의 도구들이 moviefinder 서버 아래에 나타납니다.

참고 사항

• 장르 목록(/genre/movie/list)은 한 번 가져온 후 discover_movies를 위해 메모리에 캐시됩니다.

• 401 / 404 / 429 응답은 실행 가능한 메시지와 함께 표시됩니다.

• 입력값은 TMDB 호출 전에 zod를 통해 검증됩니다.