Umami MCP

npx add-mcp 'https://cloud.umami.is/mcp'

@umami/mcp

Model Context Protocol 서버 for Umami 애널리틱스. Claude, ChatGPT, Cursor 및 기타 MCP 클라이언트가 @umami/api-client를 통해 Umami API를 호출하는 읽기 전용 도구를 사용하여 웹사이트 트래픽에 대한 질문에 답할 수 있게 해줍니다.

MCP 서버는 데이터베이스와 직접 통신하지 않습니다. 모든 도구는 공개 API와 웹 앱과 동일한 사용자/팀 권한 검사를 거칩니다.

도구

도구	용도
list_websites	접근 가능한 웹사이트 찾기 (websiteId를 얻으려면 먼저 호출).
get_website_daterange	기록된 데이터가 있는 가장 이른 날짜와 가장 최근 날짜.
get_website_stats	페이지뷰, 방문자, 방문 수, 이탈률, 체류 시간 + 이전 기간.
get_website_traffic	분, 시간, 일, 월 또는 연 단위 페이지뷰/방문 시계열.
get_website_metrics	상위 페이지, 리퍼러, 채널, 국가, 브라우저, 기기, UTM, 이벤트.
get_realtime	현재 활동 중인 방문자.
get_events	개별 추적 이벤트 (페이지네이션).
get_event_stats	맞춤 이벤트 합계 + 이전 기간.
get_event_series	시간에 따른 맞춤 이벤트 수, 이벤트 이름별 그룹화.
get_event_properties	맞춤 이벤트 속성 이름 또는 한 속성의 값.
get_sessions	방문자 세션 (페이지네이션).
get_session_stats	세션 수준 합계: 방문자, 방문 수, 페이지뷰, 이벤트, 국가.
get_annotations	변경 사항을 설명하는 타임라인의 날짜 메모 (출시, 캠페인).
list_segments	저장된 세그먼트 및 코호트; filters.segment / .cohort를 통해 ID 전달.
get_session	활동 타임라인과 속성이 포함된 단일 세션.
list_funnels	단계가 포함된 저장된 퍼널 (run_funnel에 대한 funnelId 획득).
run_funnel	저장된 funnelId 또는 임시 페이지/이벤트 단계에서의 전환 퍼널.
get_goals	범위에 대한 전환, 방문자 및 비율이 포함된 저장된 목표.
run_journey	방문자가 가장 많이 거치는 경로.
run_retention	코호트 유지율 표.
run_attribution	전환에 대한 첫/마지막 클릭 기여도.
get_revenue	수익 합계, 시계열 및 세분화.
get_performance	Core Web Vitals (LCP, INP, CLS, FCP, TTFB) 백분위수, 추세, 세분화.

모든 도구는 읽기 전용입니다. 날짜는 ISO 8601 형식이며, 결과는 페이지 크기 상한이 있는 페이지네이션으로 제공됩니다.

원격: Umami Cloud

기존 Cloud API 키를 사용하여 https://cloud.umami.is/mcp에 연결하세요:

Authorization: Bearer api_<your-cloud-api-key>

사용자 정의 헤더를 지원하는 클라이언트는 x-umami-api-key를 대신 사용할 수 있습니다. 두 헤더가 모두 제공되는 경우 동일한 키를 포함해야 합니다. API 키 또는 베어러 헤더 구성을 지원하는 클라이언트를 사용하세요.

Cloud MCP는 Cloud API와 동일한 구독 요구 사항 및 웹사이트/팀 권한을 가집니다. 모든 도구는 Cloud API 게이트웨이를 호출하며, 게이트웨이는 키를 검증하고 요청을 해당 리전으로 라우팅합니다.

원격: 자체 호스팅

Umami 인스턴스의 설정 → API 키에서 API 키를 생성한 후, Streamable HTTP 엔드포인트로 MCP 클라이언트를 구성하세요:

https://your-umami.example.com/mcp

키를 사용하여 인증 헤더를 설정하세요:

Authorization: Bearer umami_<your-api-key>

베어러 토큰 또는 사용자 정의 인증 헤더를 지원하는 클라이언트를 사용하세요. 엔드포인트는 자체 호스팅 API 키를 허용하며, 브라우저 로그인 토큰은 지원되지 않습니다. 도구는 읽기 전용이며 키 소유자의 기존 사용자/팀 권한을 존중합니다. 설정에서 키를 해지하면 접근이 차단됩니다. MCP는 기본적으로 비활성화되어 있습니다. 엔드포인트를 활성화하려면 MCP_ENABLED=1를 설정하세요.

로컬 / stdio

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_API_TOKEN": "umami_…"
      }
    }
  }
}

변수	설명
UMAMI_URL	자체 호스팅 인스턴스 URL (/api가 추가됨).
UMAMI_API_URL	대신 전체 API 기본 URL, 예: https://api.umami.is/v1.
UMAMI_API_TOKEN	API 키 또는 로그인 토큰 (자체 호스팅).
UMAMI_API_KEY	Umami Cloud API 키.

Cloud stdio의 경우 UMAMI_API_KEY를 설정하고 UMAMI_URL 및 UMAMI_API_TOKEN를 생략하세요:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "@umami/mcp"],
      "env": { "UMAMI_API_KEY": "api_<your-cloud-api-key>" }
    }
  }
}

예시 프롬프트

• 내 웹사이트를 보여줘.
• 지난주 example.com 방문자는 몇 명이었어?
• 이번 달 상위 10개 페이지는 무엇이었어?
• 이번 달 트래픽을 지난달과 비교해줘.
• 트래픽이 어디에서 오고 있어?
• 어제 발생한 가입 이벤트는 무엇이었어?
• 사용자 abc123의 세션을 보여줘.
• 지난달 체크아웃 이벤트에서 사람들이 선택한 요금제는 무엇이었어?
• 이번 주 매일 발생한 가입 이벤트 수는 얼마야?
• 지난달 체크아웃 퍼널을 실행해줘.
• 이번 분기 목표 대비 성과는 어때?
• 모바일에서 LCP가 가장 나쁜 페이지는 어디야?
• 트래픽이 급증한 날에 무슨 일이 있었어?

프로그래밍 방식 사용

import { UmamiClient } from '@umami/api-client';
import { createUmamiMcpServer } from '@umami/mcp';

const server = createUmamiMcpServer({
  client: new UmamiClient({ baseUrl, token }),
});

createUmamiMcpHttpHandler({ createClient })는 모든 웹 프레임워크에 임베딩하기 위한 Streamable HTTP 핸들러를 반환합니다. 호스트는 베어러 토큰을 검증하고 authInfo를 전달합니다.