mcp-server-pexels

Pexels 스톡 사진 및 동영상 검색을 위한 MCP 서버입니다. LLM에 최적화되어 있습니다.

Pexels는 무료 스톡 사진과 동영상을 제공합니다.

기능

• 사진 검색 — 필터(검색어, 방향, 크기, 색상, 로케일)를 사용하여 사진 검색

• 동영상 검색 — 동영상 검색, 1920x1080에 가장 가까운 HD .mp4 자동 선택

• 상세 정보 가져오기 — ID를 통해 사진/동영상의 전체 메타데이터 검색

• 지능형 캐싱 — 검색 시 10분 TTL, ID 조회 시 60분 TTL 적용

• 오류 처리 — 유용한 메시지와 함께 정상적인 실패 처리 (MCP 모범 사례 준수)

• 출처 표기 — 모든 결과에 사진작가 크레딧 필수 포함

사전 요구 사항

• Node.js v20 이상

• Pexels API 키 (pexels.com/api에서 무료 발급)

빠른 시작 (2분)

1. API 키 발급

pexels.com/api에서 가입하세요. 무료이며 신용카드가 필요하지 않습니다.

2. 서버 빌드

npm install && npm run build

3. Claude Desktop에 추가

~/Library/Application Support/Claude/claude_desktop_config.json (Mac) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows) 파일을 열고 다음을 추가하세요:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-pexels/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_PEXELS_API_KEY"
      }
    }
  }
}

Windows 참고: node.exe의 전체 경로를 사용하거나 Node를 PATH에 추가하세요. Windows에서도 경로에 슬래시(/)를 사용할 수 있습니다.

4. Claude Desktop 재시작

이제 pexels_search_photos, pexels_search_videos, pexels_get_details를 서버에서 사용할 수 있습니다.

구성

.mcp.json 또는 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

환경 변수

환경 변수에 PEXELS_API_KEY를 설정하세요. 로컬 개발을 위해 .env 파일을 생성하세요:

PEXELS_API_KEY=your_pexels_api_key

개발

npm run dev      # watch mode
npm run inspector # MCP Inspector
npm test          # run tests

도구

아키텍처

• src/index.ts — 진입점, MCP 서버 설정

• src/tools/ — 도구 구현

• src/shared/ — 캐시, API 클라이언트, 오류, 타입, 동영상 선택기

• src/utils/ — Zod 유효성 검사 스키마

엔지니어링 결정

호환성

StdioClientTransport를 통해 @modelcontextprotocol/sdk v1.29+와 테스트되었습니다. 통합 테스트 스위트는 빌드된 서버를 생성하고 모든 도구 호출을 SDK의 CallToolResultSchema 및 ContentBlockSchema에 대해 검증합니다.

모든 성공적인 응답의 마지막 콘텐츠 요소에는 타입이 지정된 데이터(id, kind, creatorName, dimensions, URLs)를 포함하는 구조화된 JSON 블록이 추가됩니다. 다운스트림 클라이언트와 에이전트 프레임워크는 마크다운 텍스트를 정규식으로 파싱하는 대신 이 블록을 직접 파싱할 수 있습니다. |

향후 개선 사항

• 도구 실행 텔레메트리 — 캐시 적중/미적중, 쿼리 실행 시간, 오류율에 대한 구조화된 로깅을 추가합니다. 이는 프로덕션 환경에서 AI 에이전트의 문제 해결을 지원하고 관측 가능성 모범 사례를 보여줍니다. |

• 메트릭 엔드포인트 — 모니터링을 위해 카운터(처리된 요청, 캐시 적중률, 남은 API 할당량)를 노출합니다. |

• 사용자 지정 TTL 구성 — 사용자가 환경 변수를 통해 캐시 TTL을 조정할 수 있도록 합니다. |

커뮤니티 기여

• 환영합니다! 🌟

라이선스

비공식 커뮤니티 프로젝트입니다. Pexels와 관련이 없습니다.