Umami MCP

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

@umami/mcp

Mô hình Ngữ cảnh Giao thức máy chủ cho Umami phân tích. Cho phép Claude, ChatGPT, Cursor và các máy khách MCP khác trả lời các câu hỏi về lưu lượng truy cập trang web của bạn bằng các công cụ chỉ đọc gọi API Umami thông qua @umami/api-client.

Máy chủ MCP không bao giờ kết nối trực tiếp với cơ sở dữ liệu; mọi công cụ đều đi qua API công khai và cùng các kiểm tra quyền người dùng/nhóm như ứng dụng web.

Công cụ

Công cụ	Mục đích
list_websites	Tìm các trang web bạn có thể truy cập (gọi trước để lấy websiteId).
get_website_daterange	Ngày sớm nhất và muộn nhất có dữ liệu được ghi lại.
get_website_stats	Lượt xem trang, khách truy cập, lượt truy cập, tỷ lệ thoát, thời lượng + kỳ trước.
get_website_traffic	Chuỗi thời gian lượt xem trang/lượt truy cập theo phút, giờ, ngày, tháng hoặc năm.
get_website_metrics	Các trang hàng đầu, nguồn giới thiệu, kênh, quốc gia, trình duyệt, thiết bị, UTM, sự kiện.
get_realtime	Khách truy cập đang hoạt động ngay bây giờ.
get_events	Các sự kiện được theo dõi riêng lẻ (phân trang).
get_event_stats	Tổng số sự kiện tùy chỉnh + kỳ trước.
get_event_series	Số lượng sự kiện tùy chỉnh theo thời gian, nhóm theo tên sự kiện.
get_event_properties	Tên thuộc tính sự kiện tùy chỉnh, hoặc giá trị của một thuộc tính.
get_sessions	Phiên khách truy cập (phân trang).
get_session_stats	Tổng cấp phiên: khách truy cập, lượt truy cập, lượt xem trang, sự kiện, quốc gia.
get_annotations	Ghi chú có ngày tháng trên dòng thời gian (ra mắt, chiến dịch) để giải thích thay đổi.
list_segments	Phân đoạn và nhóm đã lưu; truyền ID qua filters.segment / .cohort.
get_session	Một phiên với dòng thời gian hoạt động và thuộc tính của nó.
list_funnels	Phễu đã lưu với các bước của chúng (lấy funnelId cho run_funnel).
run_funnel	Phễu chuyển đổi từ funnelId đã lưu hoặc các bước trang/sự kiện tùy chỉnh.
get_goals	Mục tiêu đã lưu với chuyển đổi, khách truy cập và tỷ lệ cho một phạm vi.
run_journey	Các đường dẫn phổ biến nhất mà khách truy cập thực hiện.
run_retention	Bảng giữ chân nhóm.
run_attribution	Phân bổ lần nhấp đầu tiên/cuối cùng cho một chuyển đổi.
get_revenue	Tổng doanh thu, chuỗi và phân tích chi tiết.
get_performance	Core Web Vitals (LCP, INP, CLS, FCP, TTFB) phần trăm, xu hướng, phân tích chi tiết.

Tất cả các công cụ đều chỉ đọc. Ngày tháng theo ISO 8601; kết quả được phân trang với giới hạn cứng về kích thước trang.

Từ xa: Umami Cloud

Kết nối với https://cloud.umami.is/mcp bằng khóa API Cloud hiện có của bạn:

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

Các máy khách hỗ trợ tiêu đề tùy chỉnh có thể sử dụng x-umami-api-key thay thế. Nếu cả hai tiêu đề được cung cấp, chúng phải chứa cùng một khóa. Sử dụng máy khách hỗ trợ cấu hình khóa API hoặc tiêu đề bearer.

Cloud MCP có cùng yêu cầu đăng ký và quyền trang web/nhóm như Cloud API. Tất cả các công cụ gọi cổng Cloud API, cổng này xác thực khóa và định tuyến yêu cầu đến khu vực của bạn.

Từ xa: tự lưu trữ

Tạo khóa API trong Cài đặt → Khóa API trong phiên bản Umami của bạn, sau đó cấu hình máy khách MCP của bạn với điểm cuối Streamable HTTP:

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

Đặt tiêu đề ủy quyền bằng khóa của bạn:

Authorization: Bearer umami_<your-api-key>

Sử dụng máy khách hỗ trợ mã thông báo bearer hoặc tiêu đề ủy quyền tùy chỉnh. Điểm cuối chấp nhận khóa API tự lưu trữ; mã thông báo đăng nhập trình duyệt không được hỗ trợ. Các công cụ chỉ đọc và tôn trọng quyền người dùng/nhóm hiện có của chủ sở hữu khóa. Thu hồi khóa trong Cài đặt để ngắt kết nối truy cập. MCP bị tắt theo mặc định. Đặt MCP_ENABLED=1 để bật điểm cuối.

Cục bộ / stdio

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

Biến	Mô tả
UMAMI_URL	URL phiên bản tự lưu trữ (/api được thêm vào).
UMAMI_API_URL	URL cơ sở API đầy đủ thay thế, ví dụ: https://api.umami.is/v1.
UMAMI_API_TOKEN	Khóa API hoặc mã thông báo đăng nhập (tự lưu trữ).
UMAMI_API_KEY	Khóa API Umami Cloud.

Đối với Cloud stdio, đặt UMAMI_API_KEY và bỏ qua UMAMI_URL và UMAMI_API_TOKEN:

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

Ví dụ về lời nhắc

• Hiển thị các trang web của tôi.
• Có bao nhiêu khách truy cập example.com trong tuần trước?
• 10 trang hàng đầu tháng này là gì?
• So sánh lưu lượng truy cập tháng này với tháng trước.
• Lưu lượng truy cập đến từ đâu?
• Những sự kiện đăng ký nào đã xảy ra hôm qua?
• Hiển thị phiên cho người dùng abc123.
• Mọi người đã chọn gói giá nào trong sự kiện thanh toán tháng trước?
• Có bao nhiêu sự kiện đăng ký được kích hoạt mỗi ngày trong tuần này?
• Chạy phễu thanh toán của tôi cho tháng trước.
• Chúng ta đang tiến triển thế nào so với mục tiêu quý này?
• Trang nào có LCP tệ nhất trên thiết bị di động?
• Điều gì đã xảy ra vào ngày lưu lượng truy cập tăng đột biến?

Sử dụng lập trình

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

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

createUmamiMcpHttpHandler({ createClient }) trả về trình xử lý Streamable HTTP để nhúng vào bất kỳ khung web nào; máy chủ xác minh mã thông báo bearer và chuyển authInfo.