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

• 명확한 구조화된 도구 출력 및 명시적 오류 범주

Related MCP server: umami-mcp-server

요구 사항

• 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

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

1. API 키 모드

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

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

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 환경 변수를 사용할 수 있는지 확인하세요.

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

1. umami_ping

2. umami_list_websites

3. umami_get_stats

4. 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