umami-mcp-server

Umami Analytics용 MCP 서버입니다. 읽기 전용이며, Umami Cloud와 자체 호스팅 인스턴스 모두에서 동작합니다. 에포크 밀리초와 UUID 대신 last_month 같은 기간과 example.com 같은 사이트 이름을 사용합니다.

웹사이트 검색, 트래픽 통계, 시계열 데이터, 순위 집계, 커스텀 이벤트, 개별 세션, 한 번의 호출로 끝나는 전체 보고서, 웹사이트/사용자/팀에 대한 전체 관리자 CRUD, 클라이언트 온보딩을 위한 복합 도구, 그리고 Umami API의 다른 모든 것을 위한 원시 GET 우회 도구까지 총 25개의 도구를 제공합니다.

관리자 도구(사용자, 팀, 웹사이트 생성, 모든 항목 삭제)에는 관리자 로그인 또는 관리자 API 키가 있는 자체 호스팅 Umami가 필요합니다. Umami Cloud는 API에서 사용자 또는 팀 관리 기능을 제공하지 않으므로, Cloud를 지정하면 혼란스러운 404 대신 명확한 오류를 반환합니다.

설치

npm install
npm run build

Related MCP server: Plausible MCP

구성

.env.example 파일을 복사하고 두 가지 인증 방식 중 하나를 채워 넣으세요.

Umami Cloud

Settings, API keys에서 키를 생성하세요.

Self-hosted

공통

연결

Claude Desktop 또는 Claude Code

claude_desktop_config.json에 추가하거나 claude mcp add를 실행하세요:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp-server/dist/index.js"],
      "env": {
        "UMAMI_API_KEY": "your-key",
        "UMAMI_TIMEZONE": "America/New_York",
        "UMAMI_DEFAULT_WEBSITE": "example.com"
      }
    }
  }
}

자체 호스팅 인스턴스라면 UMAMI_BASE_URL과 함께 API 키 또는 사용자 이름/비밀번호 쌍 중 하나를 넣으세요.

MCP Inspector

UMAMI_API_KEY=your-key npm run inspect

도구

분석(읽기 전용)

관리자: 웹사이트 (self-hosted, admin 로그인 또는 키)

관리자: 사용자 (self-hosted)

관리자: 팀 (self-hosted)

프로비저닝

서브 네트

모든 데이터 도구는 response_format 파라미터를 받습니다. markdown은 읽기 좋은 요약을, json은 구조화된 데이터를 반환합니다. 모든 파괴적인 도구(reset, delete, remove)는 confirm: true 인자가 필수이며, 이를 포함하지 않으면 호출이 거부되고 별다른 추가 확인 단계가 없으므로, 그 인자가 실행 전 최종 확인 지점입니다.

날짜 범위

range에는 다음 중 하나를 전달합니다:

• Relative(상대적): 30m, 24h, 7d, 4w, 3mo, 1y

• Named(명명된): today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year, mtd, ytd, all_time

또는 start_date와 end_date를 YYYY-MM-DD, 전체 ISO 8601 타임스탬프 또는 epoch 밀리초로 전달하세요. 명시적 날짜가 range보다 우선합니다. 일의 경계는 UMAMI_TIMEZONE 또는 호출 시마다의 timezone 인자를 따릅니다.

필터

대부분의 도구는 쿼리를 분할하는 filters 객체를 받습니다:

{ "country": "US", "device": "mobile", "path": "/pricing" }

지원하는 키: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.

세부 집계 차원

umami_get_metrics 및 umami_traffic_report의 breakdowns 인자에 사용: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId.

예시

연결 후 자연스럽게 요청하세요:

• "지난달 사이트 실적은 그 전달 대비 어땠나?" → umami_get_stats에서 range=last_month

• "지난 30일간의 전체 분석 요약을 주세요" → umami_traffic_report

• "어느 도착 페이지가 이탈률이 가장 높은가?" → umami_get_metrics에서 type=entry, expanded=true

• "이번 주 접촉 폼 제출은 몇 번?" → umami_get_events_series에서 event=contact-form-submit

• "플로리다 모바일 방문자의 상위 페이지를 보여줘" → umami_get_metrics에서 type=path, filters={ device: "mobile", region: "US" }

• "그 세션이 사이트에서 무엇을 했는지?" → umami_list_sessions 후 umami_get_session

• "새 클라이언트 트래킹, 전용 팀, 그리고 제에게 권한을 부여해줘" → umami_onboard_client에서 website_name, domain, team_name, grant_user_id

• "이 사이트가 라이브되기 전에 테스트 데이터를 삭제해줘" → umami_reset_website에서 confirm=true

디자인 노트

• 웹사이트 해석. 모든 도구의 website 인자는 UUID, 이름 또는 도메인을 받을 수 있습니다. 이름과 도메인은 60초 캐시된 웹사이트 목록과 대조되며, 조용히 잘못된 추측을 하는 대신 명시적인 모호성 오류가 반환됩니다. 웹사이트를 생성, 업데이트 또는 삭제하면 캐시가 즉시 새로고침됩니다.

• 전체 재생/히트맵 설정(단순 토글이 아닌). umami_update_website는 Umami의 replayConfig가 받아들이는 모든 필드를 노출합니다. 활성화 플래그, 재생과 히트맵의 독립 샘플링 비율, PII 마스크 수준, 차단 선택자, 최대 녹화 시간이 포함됩니다. Umami 자체 문서에는 maxDuration의 단위가 일관되지 않게 나와 있습니다(한 예는 밀리초를, 다른 예는 초를 암시합니다). 추측하는 대신 umami_get_recorder_config는 트래커가 실제로 호출하는 것과 동일한 공개 엔드포인트를 읽으므로, 문서의 어떤 예를 신뢰할 필요 없이 저장된 후 실제 적용된 값을 확인할 수 있습니다.

• 파생 지표. Umami는 원시 bounces 및 totaltime 수치를 반환합니다. 이탈률, 방문당 조회수, 평균 방문 시간이 여기서 계산되므로 모든 응답을 바로 읽을 수 있습니다.

• 부분 실패. umami_traffic_report는 세부 분석을 병렬로 실행하고, 인스턴스가 지원하지 않는 차원을 버리되, 전체 보고서를 실패시키지 않습니다. 대신 건너뛴 차원의 이름을 명시합니다. 차원 지원은 Umami 버전마다 다르기 때문에 이는 중요합니다.

• 파괴적인 작업은 옵트인이며, 이중 확인을 하지 않습니다. umami_reset_website, umami_delete_website, umami_delete_user, umami_remove_team_user, umami_delete_team은 모두 리터럴 confirm: true 인자를 요구하고, 그렇지 않으면 실행에 실패합니다. 별도의 “정말 확인 하시겠습니까?”와 같은 절차는 없습니다. 도구 호출 자체가 확인이므로 에이전트(또는 사용자)는 실제로 의도하는 경우에만 confirm: true를 전달해야 합니다.

• umami_onboard_client는 best-effort(최선 노력) 방식이지, 트랜잭션이 아닙니다. Umami의 API는 다단계 트랜잭션을 지원하지 않습니다. 팀 생성은 성공했지만 웹사이트 단계가 실패하면 팀은 그대로 유지되며, 오류 메시지는 이 사실과 다음에 확인해야 할 사항을 명시적으로 알려줍니다. 조용히 롤백하거나 부분 상태를 숨기지 않습니다.

• 탈출구. umami_api_get은 의도적으로 GET 전용이며 위의 관리 도구들과 분리되어 있습니다. 생성, 수정, 초기화, 삭제 등 어떤 것도 할 수 없습니다.

• 응답 크기. 응답은 25,000자로 상한되며, limit, offset 또는 더 좁은 범위를 안내하는 메시지가 포함됩니다.

테스트

npm test

test/smoke.mjs는 모의(mock) Umami API를 띄우고, stdio를 통해 실제 MCP 클라이언트를 연결하며, 분석 도구와 오류 경로를 함께 실행합니다. test/auth.mjs는 자체 호스팅 로그인 인증과 캐시된 베어러 토큰이 만료되었을 때 발동하는 토큰 갱신을 다룹니다. test/admin.mjs는 웹사이트/사용자/팀 CRUD, 팀 멤버십, 복합 온보딩 도구를 다루며 모든 파괴적 도구도 confirm=true가 없으면 실행을 거부하는지 확인합니다.

검증 대상

2026년 8월 기준 Umami v3 API 참조 문서: /websites, /websites/:id, /websites/:id/stats, /pageviews, /metrics, /metrics/expanded, /events/series, /active, /daterange, /sessions, /sessions/:id, /sessions/:id/activity, /websites/:id/reset, /users, /admin/users, /users/:id, /users/:id/websites, /users/:id/teams, /teams, /teams/join, /teams/:id, /teams/:id/users, /teams/:id/users/:userId, /teams/:id/websites. 클라우드 요청은 베어러 토큰과 함께 https://api.umami.is/v1로 전송되며, 자체 호스팅 요청은 {base}/api로 전송됩니다. 사용자 및 팀 관리 엔드포인트는 자체 호스팅 인스턴스에만 존재합니다.

라이선스

MIT