Umami MCP Server

Umami Analytics용 Model Context Protocol 서버입니다. Claude, Cursor 또는 모든 MCP 클라이언트에게 트래픽에 대해 물어보고 — 웹사이트를 생성·관리하도록 할 수 있습니다 — 자격 증명은 당신의 컴퓨터에 그대로 유지됩니다.

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

왜 만들어졌나

Umami에는 공식 MCP 서버가 없습니다. 커뮤니티 서버가 여러 개 있으며, 단순히 광범위한 API 커버리지를 원한다면 0xtlt/umami-mcp를 먼저 보세요. 이 서버보다 더 많은 API를 감쌉니다. 일부 오래된 서버(jakeyShakey, mikusnuz, mittwald, Macawls)는 v2 API를 대상으로 작성되어 최신 인스턴스에서 작동하지 않습니다. v3가 별칭 없이 이름을 바꿨기 때문입니다:

이 서버는 다른 서버들이 하지 않는 두 가지를 위해 존재합니다:

1. 완전하고 검증된 v3 리포트 커버리지. 7가지 v3 리포트 유형 모두 — 퍼널, 리텐션, 저널, 목표, 수익, 기여, UTM — 실제 Umami 3.3.1 인스턴스에서 테스트되었습니다. 리포트 엔벨로프는 틀리기 쉽습니다. 날짜는 filters가 아닌 parameters에 ISO-8601 문자열로 넣어야 하며, 나머지 API가 사용하는 epoch 밀리초가 아닙니다. 기여는 first-click / last-click을 사용하며, 당신이 추측할 camelCase 표기가 아닙니다.

2. 불리언이 아닌 기능 모델. 아래 참조.

Related MCP server: Umami MCP Server

보안 모델

분석 MCP 서버는 지금까지 기록된 모든 방문자 세션을 읽을 수 있는 자격 증명을 보유하며, 허용한다면 그 전부를 삭제할 수도 있습니다. 설계는 그 사실에서 비롯됩니다.

자격 증명은 절대 당신의 환경을 떠나지 않습니다. 설정은 프로세스 환경에서만 읽습니다. 텔레메트리, phone-home, 호스팅 릴레이가 없습니다. 이 서버가 접촉하는 유일한 호스트는 당신이 설정한 UMAMI_URL입니다. 직접 호스팅하면 분석 데이터에 관한 어떤 것도 제3자(이 소프트웨어 작성자 포함)에게 도달하지 않습니다.

Umami 인스턴스에 연결할 호스팅 엔드포인트를 제공하는 Umami MCP는 조심하세요. 자체 호스팅 Umami에는 API 키가 없으므로, "편리한" 호스팅은 관리자 비밀번호를 남의 서버로 보내는 것을 의미합니다.

기본적으로 최소 권한. 서버는 read 모드로 시작합니다. 권한을 넓히는 것은 의도적인 행위입니다:

제외된 도구는 아예 등록되지 않으므로 모델의 도구 목록에 절대 나타나지 않습니다. 이 부분이 READONLY=true 플래그와 다른 점입니다. 광고된 적 없는 도구는, 예를 들어 리퍼러 문자열이나 당신의 분석 데이터 안의 페이지 제목에 숨겨진 프롬프트 주입 지시로 호출될 수 없습니다. 잊거나 우회할 런타임 검사가 없습니다. 도구 자체가 없기 때문입니다.

파괴적 작업은 실제 값과 대조해 확인하는 입력형 확인이 필요합니다. umami_delete_website는 confirmDomain 인자를 받아 실제 레코드를 가져온 다음, 일치하지 않으면 거부합니다. 잘못된 웹사이트 UUID를 집어든 모델은 데이터가 날아가는 대신 오류를 받습니다.

자격 증명은 클라이언트 설정에 들어가지 않습니다. ~/.claude.json이나 mcp.json 안에 비밀번호를 요구하는 대신, 서버는 당신이 제어하는 ~/.config/umami-mcp/env 파일에서 읽고, 해당 파일을 다른 사용자가 읽을 수 있으면 경고합니다. 자격 증명 참조.

비밀은 출력에서 마스킹됩니다. MCP 출력은 모델로 흘러들어가고 종종 채팅 기록에도 남는데, 이는 번복할 수 없습니다. 비밀번호, Bearer 토큰, JWT는 프로세스를 떠나기 전에 모든 오류와 응답에서 삭제됩니다.

자격 증명을 네트워크로 유출하지 않습니다. 원격 호스트에 대한 평문 HTTP는 시작 시 거부되며, 로컬 개발을 위한 localhost에서만 허용됩니다.

설치

실행 방법은 세 가지입니다. 자체 호스팅이 기본값이자 권장 방식입니다 — 호스팅 인스턴스는 아무것도 클론하지 않고 2분 안에 시도해볼 수 있도록 존재합니다.

직접 호스팅하면서 Claude web에서 사용하려면 UMAMI_MCP_OAUTH=true와 함께 자신의 도메인 뒤에서 실행하세요. 그러면 당신의 어떤 것도 다른 사람의 인프라에 닿지 않습니다.

1. 호스팅 인스턴스 사용하기 (설치할 것 없음)

Claude에서 다음 주소를 가리키는 커스텀 커넥터를 추가하세요:

https://umami-mcp.asif.dev/mcp

동의 화면에서 자신의 Umami URL과 로그인 정보를 요청받습니다. 자격 증명이 처리되는 방식은 Claude web, Cowork 및 Claude Code on web을 참조하세요.

2. 소스에서

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

그런 다음 자격 증명을 설정하고 클라이언트에 등록하세요:

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

Node 20 이상이 필요합니다.

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm: 아직 게시되지 않았습니다. 게시되면 npx -y @asif2bd/umami-mcp가 위의 클론-빌드 단계를 대체할 것입니다. 그때까지는 소스 또는 Docker를 사용하세요.

자격 증명

자체 호스팅 Umami에는 API 키가 없으므로, 이 서버가 보유하는 자격 증명은 실제 계정 비밀번호입니다. MCP 클라이언트는 보통 이를 구성 JSON(~/.claude.json, mcp.json 등)에 포함하길 원하는데, 이 파일들은 널리 읽힐 수 있고, 이슈와 화면 공유에 붙여넣어지며, 일부 클라이언트는 기기 간에 동기화합니다.

따라서 이 서버는 대신 당신이 제어하는 파일에서 자격 증명을 읽습니다. 한 번만 생성하세요:

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

서버가 자동으로 로드합니다. 다른 사용자가 읽을 수 있으면 시작 시 경고합니다.

조회 순서 — 먼저 찾은 파일이 우선하며, 실제 환경 변수는 항상 파일보다 우선합니다. 따라서 원할 때 클라이언트 설정에서 설정을 전달할 수도 있습니다:

1. $UMAMI_MCP_ENV_FILE, 설정된 경우

2. ~/.config/umami-mcp/env (또는 $XDG_CONFIG_HOME/umami-mcp/env)

3. ./.env (작업 디렉터리)

클라이언트 연결

Claude Code

위의 자격 증명 파일을 사용하면 등록 정보에 비밀이 전혀 포함되지 않습니다:

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

체크아웃한 디렉터리의 절대 경로를 사용하세요. Node가 nvm 아래에 있다면 인터프리터 전체 경로도 지정하세요. MCP 클라이언트는 셸 프로필을 로드하지 않기 때문입니다:

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

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

모든 것을 한 곳에 두고 싶다면 환경 변수도 여전히 작동하며 파일보다 우선합니다:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

작동 확인

클라이언트에게 umami_whoami를 실행하라고 요청하세요. 인스턴스, 계정, 권한 모드를 보고합니다. 연결을 확인하고 서버가 얼마나 많은 작업을 허용하는지 확인하는 가장 빠른 방법입니다:

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

그런 다음 시도해보세요: "내 Umami 웹사이트 목록을 보여줘", 또는 "지난주 상위 페이지는 무엇이었나?"

Claude web, Cowork 및 Claude Code on web

이런 클라이언트들은 로컬 프로세스를 실행할 수 없으므로 공개 HTTPS MCP 서버가 필요합니다. 그리고 커넥터 UI는 OAuth만 허용하며, 정적 Bearer 토큰이나 커스텀 헤더를 위한 필드가 없습니다.

당연한 방식으로, 즉 한 벌의 Umami 자격 증명을 박아 넣고 인증 없이 호스팅하면 그 URL은 해당 Umami로 가는 공개 프록시가 됩니다. 그래서 이 서버는 대신 OAuth를 사용하며, 자격 증명 저장소가 되는 일 없이 그렇게 합니다.

호스팅 인스턴스 사용

Claude에 이 URL로 커스텀 커넥터를 추가하세요:

https://umami-mcp.asif.dev/mcp

Claude가 스스로 등록하고, 동의 화면으로 안내한 다음 당신 자신의 Umami URL, 사용자 이름, 비밀번호를 요구합니다. 호스트의 다른 사용자와 공유되는 것은 없습니다.

직접 호스팅

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

키를 한 번 생성하고 보관하세요:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

UMAMI_URL도 설정하면 사용자가 선택하는 대신 모든 사용자를 한 인스턴스에 고정할 수 있습니다.

자격 증명의 처리 방식

동의 화면은 사용자가 지정한 Umami 인스턴스에 대해 자격 증명을 검증한 다음, AES-256-GCM으로 액세스 토큰에 봉인합니다. 서버는 세션 테이블을 유지하지 않고 자격 증명도 저장하지 않습니다. 각 요청은 토큰을 해독하고, 그 한 사용자로 범위가 제한된 MCP 서버를 만든 다음 호출을 처리하고 폐기합니다.

솔직한 트레이드오프: UMAMI_MCP_TOKEN_KEY를 가진 사람은 누구든 가로챈 토큰을 해독할 수 있습니다. 이를 배포에서 가장 민감한 값으로 취급하세요. 순환(rotation)시키면 발급된 모든 토큰이 무효화되며, 이것이 의도된 폭발 반경 (blast-radius) 통제입니다.

파괴적 도구는 사용자가 어떤 권한을 선택하든 OAuth를 통해 절대 노출되지 않습니다. 이들의 입력형 확인 가드는 자신이 삭제할 대상을 볼 수 있는 로컬 운영자를 전제로 하며, 원격 호출자에게 그 내용을 보여줄 수 없습니다.

일반 HTTP 서비스로 실행

UMAMI_MCP_OAUTH 없이 UMAMI_MCP_TRANSPORT=http를 설정하면 /mcp 단일 테넌트 엔드포인트와 /health를 사용할 수 있습니다.

이 모드에서 서버는 자체 인증이 없습니다. 포트에 도달할 수 있는 사람은 누구나 당신의 Umami 자격 증명을 사용할 수 있습니다. 루프백에서 실행하고 터널로 연결하세요:

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

서버는 루프백이 아닌 다른 곳에 바인딩되면 시작 시 경고합니다.

도구

시간 범위

모든 분석 도구는 epoch 밀리초 대신 24h, 7d, 30d, 12m, today, yesterday 같은 period 단축 표기를 허용합니다. 모델은 "최근 30일" 같은 표현은 안정적으로 처리하지만 타임스탬프 산술은 불안정하며, 잘못 계산된 epoch는 오류 없이 잘못된 기간의 데이터를 반환합니다. epoch 밀리초 단위의 명시적 startAt/endAt도 여전히 작동하며 우선순위를 가집니다.

구성

모든 옵션은 .env.example을 참조하세요. 핵심 사항:

권장 설정

관리자 로그인을 재사용하는 대신 MCP 서버 전용 Umami 계정을 만들고 필요한 웹사이트만 부여하세요. 이렇게 하면 자격 증명이 노출되더라도 피해 범위는 삭제할 수 있는 봇 계정 하나로 제한됩니다 — 관리자 계정이 아닙니다.

호환성

Umami 3.3.1(자체 호스팅, PostgreSQL)에서 검증되었습니다. Umami Cloud는 UMAMI_API_KEY를 통해 작동합니다. Umami v2는 지원되지 않습니다: 위에서 이름이 변경된 메트릭 유형 때문에 v2와 v3는 서로 다른 클라이언트가 필요하며, 이 서버는 v3를 대상으로 합니다.

개발

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs와 test/write-e2e.mjs는 실제 MCP 클라이언트를 통해 빌드된 서버를 라이브 인스턴스에 연결하여 구동합니다. 쓰기 테스트는 .invalid 도메인에 임시 웹사이트를 생성했다가 다시 삭제합니다. 프로덕션이 아닌 인스턴스를 대상으로 실행하세요.

기여

이슈와 풀 리퀘스트를 환영합니다. Umami v3는 약 127개의 API 라우트를 노출하며 이 서버는 그중 가장 유용한 것들을 다룹니다 — 세션 리플레이, 히트맵, 픽셀, 링크 추적, 보드, 세그먼트는 아직 매핑되지 않았습니다. 도구를 추가할 때는 계층과 destructive 플래그를 정직하게 유지하세요. 전체 안전 모델이 이에 기반하기 때문입니다.

Umami 팀이 이 프로젝트를 채택, 포크 또는 업스트림하고 싶다면 이슈를 열어 주세요 — 이것이 이 프로젝트를 만든 목적입니다.

라이선스

MIT © M Asif Rahman