Umami MCP 서버

Umami 분석을 위한 읽기 전용 MCP 서버입니다. HTTP를 통해 Umami REST API와 직접 통신하며, 자체 호스팅 Umami를 우선 지원하고 Umami Cloud API 키와도 작동합니다.

이 저장소는 상위 계층 에이전트가 매번 Umami 문서를 다시 읽지 않고도 분석 데이터를 요청할 수 있도록 구축되었습니다. 브라우저 자동화, DOM 스크래핑, 쓰기 작업은 포함하지 않습니다.

기능

가장 일반적인 Umami 분석 쿼리를 위한 읽기 전용 MCP 도구
두 가지 인증 모드:
- UMAMI_API_KEY
- UMAMI_USERNAME + UMAMI_PASSWORD
메모리 내 자체 호스팅 베어러 토큰 캐싱
사용자 이름/비밀번호 모드에서 401 발생 시 자동 재로그인 및 1회 재시도
ISO 시간 문자열 및 밀리초 타임스탬프 모두 허용
통계, 페이지뷰, 분석(breakdown), 이벤트 시리즈 전반에 걸친 공유 필터 처리
작고 유지 관리가 쉬운 모듈로 구성된 엄격한 TypeScript
명확한 구조화된 도구 출력 및 명시적 오류 범주

요구 사항

Node.js >= 20
pnpm >= 10

설치

npm 사용:

npm install -g umami-analytics-mcp

또는 설치 없이 실행:

npx -y umami-analytics-mcp

이 저장소에서 로컬 개발을 하려면:

pnpm install

구성

.env.example에서 .env 파일을 생성합니다.

cp .env.example .env

다음 인증 옵션 중 하나를 입력합니다:

API 키 모드

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

자체 호스팅 사용자 이름/비밀번호 모드

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

참고:

UMAMI_API_URL은 사이트 오리진뿐만 아니라 API 베이스를 가리켜야 합니다.
UMAMI_API_KEY와 사용자 이름/비밀번호가 모두 설정된 경우 UMAMI_API_KEY가 우선합니다.
UMAMI_DEFAULT_TIMEZONE은 도구가 시간대를 지원하고 사용자가 이를 생략할 때 사용됩니다.

로컬 실행

개발 모드:

pnpm dev

빌드 및 실행:

pnpm build
pnpm start

서버는 MCP stdio 전송을 사용하므로 클라이언트가 연결을 끊을 때까지 stdin/stdout에 연결된 상태로 유지됩니다.

npm에서 설치한 경우, 동일한 명령은 다음과 같습니다:

umami-analytics-mcp

테스트

pnpm test
pnpm build

기본적으로 건너뛰는 실제 API 통합 테스트 템플릿도 있습니다:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

MCP 인스펙터

먼저 빌드:

pnpm build

그런 다음 빌드된 서버에 대해 공식 MCP 인스펙터를 실행합니다:

npx @modelcontextprotocol/inspector node dist/cli.js

개발 중 핫 리로드를 원하면 다음도 작동합니다:

npx @modelcontextprotocol/inspector pnpm dev

게시된 패키지 경로를 테스트하려면 다음을 사용하세요:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

인스펙터 프로세스에서 동일한 Umami 환경 변수를 사용할 수 있는지 확인하세요.

인스펙터에서 권장되는 스모크 테스트 호출:

umami_ping
umami_list_websites
umami_get_stats
umami_get_breakdown

도구

`umami_ping`

구성 및 인증을 검증합니다.

예시:

{}

`umami_list_websites`

액세스 가능한 웹사이트를 나열합니다.

예시:

{}

`umami_find_website`

웹사이트 이름이나 도메인으로 퍼지 검색을 수행합니다.

예시:

{
  "query": "example.com"
}

`umami_get_stats`

웹사이트 및 시간 범위에 대한 요약 통계를 제공합니다.

예시:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

`umami_get_pageviews`

시계열 페이지뷰 및 세션 데이터를 제공합니다.

예시:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

`umami_get_breakdown`

인기 페이지, 리퍼러, 국가, 브라우저, 기기 등과 같은 분석 행을 제공합니다.

예시:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

`umami_get_active`

현재 활성 방문자 수를 반환합니다.

예시:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

`umami_get_events_series`

시간에 따른 사용자 지정 이벤트 수를 반환합니다.

예시:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

공유 필터

이 도구들은 동일한 filters 객체를 지원합니다:

path
referrer
title
query
browser
os
device
country
region
city
hostname

오류 처리

도구 오류는 다음 범주를 포함하는 구조화된 MCP 도구 결과로 반환됩니다:

config_missing
auth_failed
website_not_found
umami_http_error
network_timeout
network_error
invalid_input

모든 Stdio MCP 클라이언트에 마운트

모든 stdio 기반 MCP 클라이언트는 다음을 사용하여 이 서버를 실행할 수 있습니다:

command: npx
args: ["-y", "umami-analytics-mcp"]
env: 사용자의 Umami 변수

mcpServers 객체를 사용하는 클라이언트를 위한 예시 JSON 스니펫:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

로컬 미출시 체크아웃의 경우, 빌드된 파일을 직접 가리킬 수 있습니다:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/cli.js"]
    }
  }
}

npm에 게시

이 저장소는 이제 npm CLI 패키지로 구조화되어 있습니다.

권장 릴리스 흐름:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

참고:

umami-mcp가 이미 npm에 등록되어 있으므로 패키지 이름은 umami-analytics-mcp로 설정되었습니다.
현재 license는 안전한 자리 표시자로 UNLICENSED로 설정되어 있습니다. 허용적인 라이선스를 원하시면 실제 공개 오픈 소스 릴리스 전에 교체하세요.
나중에 자신의 npm 스코프 하에 게시하려면 package.json의 name 필드만 변경하세요.

내부 문서

이 저장소에서 사용하는 API 요약: docs/umami-api.md

Umami MCP Server