moviefinder-mcp

The Movie Database (TMDB) API를 래핑하는 MCP 서버입니다. @modelcontextprotocol/sdk와 stdio 전송 방식을 사용하여 구축되었습니다.

도구

모든 도구는 요약된 JSON(id, 제목, 연도, 개요, 평점, 포스터 URL 등)을 반환하며, 불필요한 원시 TMDB 필드는 제거됩니다.

설정

1. TMDB API 토큰 받기

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

2. https://www.themoviedb.org/settings/api 를 방문하여 API Read Access Token (v4)을 복사합니다. 이는 긴 JWT이며, v3 API 키가 아닙니다.

2. 설치 및 빌드

npm install
npm run build

3. 환경 설정

.env.example을 .env로 복사하고 토큰을 붙여넣습니다:

cp .env.example .env

TMDB_API_KEY=eyJhbGciOi...your_v4_read_access_token...

4. 서버 실행

npm start

이 서버는 stdio를 통해 MCP와 통신하며, 대화형으로 실행되는 것이 아니라 MCP 클라이언트(예: Claude Desktop)에 의해 실행되도록 설계되었습니다.

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": "eyJhbGciOi...your_v4_read_access_token..."
      }
    }
  }
}

설정을 편집한 후 Claude Desktop을 다시 시작하세요. 그러면 moviefinder 도구가 모든 대화에서 나타납니다.

스크립트

오류 처리

서버는 일반적인 TMDB 오류에 대해 유용한 메시지를 반환합니다:

• 401 — 토큰 누락 또는 잘못된 키 유형 (v4 읽기 액세스 토큰이어야 함).

• 404 — 요청한 영화 / 리소스가 존재하지 않음.

• 429 — 속도 제한 초과; Retry-After 값이 존재할 경우 포함됨.

참고 사항

• 장르 목록은 /genre/movie/list에서 한 번 가져와 메모리에 캐시됩니다.

• 포스터 URL은 https://image.tmdb.org/t/p/w500을 사용합니다.

• 데이터베이스나 로깅 프레임워크는 의도적으로 사용하지 않았습니다.