Klaviyo MCP Server

Klaviyo MCP 서버 향상

Klaviyo API와 상호 작용하기 위한 포괄적인 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 향상된 버전은 기존 MCP 서버와의 완벽한 호환성을 유지하면서 고급 분석 기능, 성능 최적화 및 강력한 오류 처리 기능을 제공합니다.

🌟 주요 특징

• 고급 분석 및 보고 : 캠페인 성과 지표, 집계된 데이터 및 자세한 통찰력에 액세스
• 포괄적인 API 범위 : 최신 개정판(2024-06-15)을 포함한 모든 Klaviyo API 엔드포인트 지원
• 성능 최적화 : 지능형 캐싱, 속도 제한 처리 및 효율적인 데이터 처리
• 강력한 오류 처리 : 폴백 메커니즘, 자세한 로깅 및 우아한 저하
• 간편한 통합 : 모델 컨텍스트 프로토콜을 통해 Claude 및 기타 LLM과 원활하게 통합

📊 분석 및 보고 기능

이 향상된 버전에서는 원래 버전에서는 사용할 수 없었던 강력한 분석 기능이 추가되었습니다.

• 캠페인 성과 지표 : 오픈율, 클릭율, 이탈율 등
• 사용자 지정 메트릭 집계 : 기간, 차원 및 측정값별로 메트릭 집계
• 수익 귀속 : 캠페인 및 흐름에서 생성된 수익을 추적합니다.
• 구독자 인사이트 : 구독자 증가, 참여 및 행동 분석

🔧 기술 향상

1. 중앙 집중식 구성 ✅

• 모든 API 매개변수에 대한 중앙 구성 시스템( src/config.js )을 생성했습니다.
• API 개정 날짜, 유효한 통계 및 기타 매개변수를 쉽게 구성할 수 있게 되었습니다.
• API 매개변수가 변경될 때 여러 파일 간의 불일치가 방지되었습니다.

2. 향상된 로깅 시스템 ✅

• 다양한 로그 수준(디버그, 정보, 경고, 오류)을 갖춘 강력한 로깅 시스템을 구현했습니다.
• API 요청 및 응답에 대한 특수 로깅이 추가되었습니다.
• 보안을 위해 로그에 민감한 데이터를 마스킹했습니다.
• 구성 가능한 로그 대상 및 자세한 정보

3. 지능형 속도 제한 ✅

• 속도 제한 오류에 대한 재시도 논리가 추가되었습니다.
• 재시도를 위한 지터가 포함된 지수 백오프 구현
• 요금 제한에 도달하면 명확한 피드백이 추가되었습니다.
• 속도 제한 중 중요 요청 우선 순위 지정

4. 성능 캐싱 ✅

• 자주 액세스되는 데이터에 대한 메모리 내 캐싱 구현
• TTL(수명)을 기반으로 캐시 무효화 추가
• 다양한 데이터 유형(메트릭, 캠페인 등)에 맞게 최적화된 캐시
• 모니터링 및 최적화를 위한 캐시 통계

5. 오류 처리 및 대체 ✅

• 모든 API 상호 작용에 대한 포괄적인 오류 처리
• 기본 요청이 실패할 경우 저하된 작업에 대한 대체 메커니즘
• 자세한 오류 메시지 및 문제 해결 정보
• JSON 구문 분석 오류 방지 및 처리

🔄 API 버전

이 향상된 버전은 최신 기능과 개선 사항이 포함된 Klaviyo API 개정판 2024-06-15 사용합니다. 이 서버는 중앙 집중식 구성 시스템을 통해 향후 API 개정판과 호환되도록 설계되었습니다.

📋 귀속

이 프로젝트는 Matt Coatsworth가 만든 기존 Klaviyo MCP 서버 의 향상된 버전입니다. 기존 작업은 이 향상된 버전의 기반이 되었습니다.

🚀 시작하기

필수 조건

• Node.js v18 이상
• API 액세스가 가능한 Klaviyo 계정
• 적절한 범위(campaigns, metrics 등)를 갖춘 개인 API 키

설치

1. 이 저장소를 복제하세요:지엑스피1
2. 종속성 설치:
   npm install
3. .env.example 기반으로 .env 파일을 만듭니다.
   cp .env.example .env
4. .env 파일을 편집하여 Klaviyo API 키를 추가하세요.
   KLAVIYO_API_KEY=your_private_api_key_here LOG_LEVEL=info LOG_FILE=/tmp/klaviyo-mcp.log LOG_RESPONSES=false NODE_ENV=development

서버 시작

자동 재로딩을 통해 개발 모드로 서버를 시작합니다.

생산용으로 사용:

MCP Inspector로 테스트

MCP Inspector를 사용하여 서버를 테스트할 수 있습니다.

이렇게 하면 사용 가능한 모든 도구와 리소스를 테스트할 수 있는 웹 인터페이스가 열립니다.

📚 문서

분석 기능 및 API 매개변수에 대한 자세한 내용은 다음을 참조하세요.

• ANALYTICS.md - 분석 기능 및 사용법에 대한 포괄적인 문서
• docs/KLAVIYO_API_REFERENCE.md - Klaviyo API 매개변수에 대한 참조

🔍 사용 예시

캠페인 성과 지표 얻기

집계된 메트릭 쿼리

캠페인 성과 요약 가져오기

🛠️ 사용 가능한 도구

분석 및 보고(향상된 버전의 새로운 기능)

• get_campaign_metrics : 특정 캠페인에 대한 성과 지표(오픈율, 클릭율 등)를 가져옵니다.
• query_metric_aggregates : 사용자 정의 분석 보고를 위해 집계된 메트릭 데이터를 쿼리합니다.
• get_campaign_performance : 캠페인에 대한 포괄적인 성과 요약을 받으세요

캠페인(향상됨)

• get_campaigns : Klaviyo에서 캠페인 가져오기
• get_campaign : Klaviyo에서 특정 캠페인을 가져옵니다.
• get_campaign_message : 템플릿 세부 정보와 함께 특정 캠페인 메시지를 받습니다.
• get_campaign_messages : 특정 캠페인에 대한 모든 메시지를 가져옵니다.
• get_campaign_recipient_estimation : 캠페인에 대한 예상 수신자 수를 가져옵니다.

프로필

• get_profiles : Klaviyo에서 프로필 가져오기
• get_profile : Klaviyo에서 특정 프로필을 가져옵니다.
• create_profile : Klaviyo에서 새 프로필을 만듭니다.
• update_profile : Klaviyo의 기존 프로필을 업데이트합니다.
• delete_profile : Klaviyo에서 프로필 삭제

목록 및 세그먼트

• get_lists : Klaviyo에서 목록 가져오기
• get_list : Klaviyo에서 특정 목록을 가져옵니다
• create_list : Klaviyo에서 새 목록을 만듭니다
• add_profiles_to_list : Klaviyo 목록에 프로필 추가
• get_segments : Klaviyo에서 세그먼트 가져오기
• get_segment : Klaviyo에서 특정 세그먼트를 가져옵니다.

이벤트 및 메트릭

• get_events : Klaviyo에서 이벤트 가져오기
• create_event : Klaviyo에서 새로운 이벤트를 만듭니다
• get_metrics : Klaviyo에서 메트릭 가져오기
• get_metric : Klaviyo에서 특정 메트릭을 가져옵니다.

흐름

• get_flows : Klaviyo에서 흐름 가져오기
• get_flow : Klaviyo에서 특정 흐름을 가져옵니다.
• update_flow_status : Klaviyo에서 흐름 상태를 업데이트합니다.

콘텐츠 관리

• get_templates : Klaviyo에서 템플릿 가져오기
• get_template : Klaviyo에서 특정 템플릿을 가져옵니다.
• create_template : Klaviyo에서 새 템플릿을 만듭니다.
• get_images : Klaviyo에서 이미지 가져오기
• get_image : Klaviyo에서 특정 이미지를 가져옵니다

전자상거래

• get_catalogs : Klaviyo에서 카탈로그 가져오기
• get_catalog_items : Klaviyo의 카탈로그에서 항목을 가져옵니다.
• get_catalog_item : Klaviyo의 카탈로그에서 특정 항목을 가져옵니다.
• get_coupons : Klaviyo에서 쿠폰 받기
• create_coupon_code : 클라비요에서 새로운 쿠폰 코드를 생성합니다

추가 도구

• get_tags : Klaviyo에서 태그 가져오기
• create_tag : Klaviyo에서 새 태그를 만듭니다.
• add_tag_to_resource : Klaviyo에서 리소스에 태그를 추가합니다.
• get_webhooks : Klaviyo에서 웹훅을 가져옵니다
• create_webhook : Klaviyo에서 새로운 웹훅을 만듭니다.
• delete_webhook : Klaviyo에서 웹훅 삭제
• request_profile_deletion : 데이터 개인정보 보호 규정 준수를 위한 프로필 삭제 요청
• get_forms : Klaviyo에서 양식 가져오기
• get_form : Klaviyo에서 특정 양식을 가져옵니다
• get_product_reviews : Klaviyo에서 제품 리뷰를 받아보세요
• get_product_review : Klaviyo에서 특정 제품 리뷰를 받아보세요

🔗 이용 가능한 리소스

• klaviyo://profile/{id} : 특정 프로필에 대한 정보를 가져옵니다.
• klaviyo://list/{id} : 특정 목록에 대한 정보를 가져옵니다.
• klaviyo://segment/{id} : 특정 세그먼트에 대한 정보를 가져옵니다.
• klaviyo://campaign/{id} : 특정 캠페인에 대한 정보를 가져옵니다.
• klaviyo://flow/{id} : 특정 흐름에 대한 정보를 가져옵니다.
• klaviyo://template/{id} : 특정 템플릿에 대한 정보를 가져옵니다.
• klaviyo://metric/{id} : 특정 메트릭에 대한 정보를 가져옵니다.
• klaviyo://catalog/{id} : 특정 카탈로그에 대한 정보를 가져옵니다.

⚠️ 알려진 문제 및 제한 사항

• Klaviyo API는 보고 엔드포인트에 속도 제한을 부과할 수 있습니다.
• 일부 메트릭은 API에서 사용 가능하기 전에 지연이 발생할 수 있습니다.
• Klaviyo 플랜에 따라 과거 데이터 가용성이 제한될 수 있습니다.
• Claude Desktop과 함께 사용할 경우 기능에 영향을 미치지 않는 JSON 구문 분석 경고가 가끔 표시될 수 있습니다.

📝 라이센스

이 프로젝트는 원래 Klaviyo MCP 서버에서 파생되었습니다. 라이선스 정보는 원래 저자에게 문의하세요.

👥 기여자

• Matt Coatsworth 의 원작
• Ivan Rivera 의 향상된 버전

🔗 외부 리소스

• 클라비요 API 문서
• 모델 컨텍스트 프로토콜
• 클로드 문서