plausible-mcp

MCP-сервер для Plausible Analytics — запрашивайте трафик, конверсии и сравнивайте временные периоды из любого ИИ-инструмента, поддерживающего Model Context Protocol.

Создан для команд, которые хотят задавать вопросы вроде:

• «Повлиял ли наш деплой во вторник на трафик на /pricing?»

• «Какой коэффициент конверсии в регистрацию на /blog в этом месяце?»

• «Как показатель отказов на этой неделе соотносится с прошлой?»

Инструменты

Все инструменты запросов только для чтения и аннотированы readOnlyHint: true.

Хостируемые развёртывания дополнительно предоставляют send_feedback, который отправляет отзывы о самом сервере (запутанные ошибки, отсутствующие возможности) в почтовый ящик Sentry User Feedback мейнтейнеров. Он регистрируется только тогда, когда сервер работает с Sentry (enableFeedbackTool).

Related MCP server: umami-mcp-server

Быстрый старт

Удалённо (хостинг)

Хостируемый экземпляр доступен по адресу https://plausible-mcp.sentry.dev.

С собственным ключом API Plausible (любой пользователь):

claude mcp add --transport http plausible https://plausible-mcp.sentry.dev/mcp --header "Authorization: Bearer YOUR_PLAUSIBLE_API_KEY"

Держите URL перед --header. --header вариадичен, поэтому если он идёт последним, он поглощает URL, и CLI завершается с ошибкой error: missing required argument 'commandOrUrl'.

Или добавьте вручную в конфигурацию вашего MCP-клиента (Claude Desktop, Cursor и т. д.):

{
  "mcpServers": {
    "plausible": {
      "url": "https://plausible-mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

Сотрудники Sentry (через OAuth 2.1 + Cloudflare Access):

Эндпоинт /internal — это сервер OAuth 2.1 — ключ API не нужен. Добавьте его как удалённый/пользовательский коннектор в любой MCP-клиент с поддержкой OAuth (Cowork, коннекторы Claude.ai, Claude Desktop):

https://plausible-mcp.sentry.dev/internal

Клиент автоматически обнаруживает эндпоинты OAuth, проводит вас через Sentry SSO (Cloudflare Access), и доступ предоставляется только идентичностям @sentry.io. Запросы выполняются с использованием общего серверного ключа API Plausible — вам никогда не нужно работать с ключом.

Хостируемый /internal на plausible-mcp.sentry.dev доступен только для Sentry и не может использоваться вне организации. Чтобы запустить /internal для другой организации, разверните самостоятельно и установите ALLOWED_EMAIL_DOMAIN на свой домен. (Публичный эндпоинт /mcp с собственным ключом не имеет таких ограничений.)

Локально (STDIO)

Если вы предпочитаете запускать локально, используйте Node.js 20 или новее:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
pnpm build

Добавьте в Claude Code:

claude mcp add plausible -e PLAUSIBLE_API_KEY=your-key -- node /path/to/plausible-mcp/dist/index.js

Или в Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/path/to/plausible-mcp/dist/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "your-key"
      }
    }
  }
}

Самостоятельное развёртывание (Cloudflare Workers)

Разверните собственный экземпляр:

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
npx wrangler deploy

Worker предоставляет два эндпоинта:

• /mcp — принесите свой ключ. Каждый пользователь передаёт свой собственный ключ API Plausible через заголовок Authorization: Bearer. На сервере не нужны общие секреты. Работает с любым MCP-клиентом, поддерживающим заголовки (Claude Code, Cursor, MCP Inspector).

• /internal — защищённый Access MCP-эндпоинт для управляемых коннекторов (Cowork, Claude.ai). Приложение Cloudflare Access с Managed OAuth стоит перед всем хостом Worker (см. ограничение ниже): Access выполняет рукопожатие OAuth 2.1 с клиентом и пересылает каждый запрос Worker с заголовком Cf-Access-Jwt-Assertion. Worker проверяет этот заголовок и запрашивает общий серверный ключ API Plausible. Access ограничен доменом(ами) электронной почты из ALLOWED_EMAIL_DOMAIN (по умолчанию sentry.io) — не привязан к Sentry при самостоятельном развёртывании; установите свой домен.

Поскольку приложение Managed OAuth должно покрывать голый хост без пути (Cloudflare отклоняет путь, когда OAuth включён — domain can not have a path if oauth is configured), оно также закрывает /mcp. Чтобы оставить публичный эндпоинт /mcp с собственным ключом, вы добавляете второе, более специфичное приложение Access, ограниченное путём /mcp с политикой Bypass. Cloudflare сопоставляет наиболее специфичный хост+путь первым, поэтому запросы /mcp полностью обходят Access, а всё остальное проходит через OAuth. Оба приложения живут на одном хосте; отдельный поддомен не требуется.

Бета / требование к клиенту. Cloudflare Access Managed OAuth находится в бете и требует MCP-клиент, поддерживающий RFC 8707 (индикаторы ресурсов). Прежде чем полагаться на этот путь, убедитесь, что ваш коннектор его поддерживает.

Настройка эндпоинта /internal (Cloudflare Access Managed OAuth)

Worker не запускает OAuth-сервер — Cloudflare Access является сервером авторизации. Нет OAUTH_KV, нет ключа cookie и нет идентификатора/секрета OAuth-клиента. Вы создаёте два приложения Access на одном хосте.

1. Создайте приложение Managed OAuth на голом хосте (Zero Trust → Access → Applications): самостоятельно размещённое приложение или приложение MCP-сервера, чей домен — plausible-mcp.sentry.dev без пути.

   • ⚠️ Не ограничивайте его /internal. Как только Managed OAuth включён, Cloudflare отклоняет любой путь с access.api.error.invalid_request: domain can not have a path if oauth is configured. Приложение должно охватывать весь хост; Worker сам обеспечивает маршрут /internal.

   • Добавьте политику Access (действие Allow), ограничивающую ваш домен электронной почты (например, @acme.com) и поставщика удостоверений.

   • Включите Managed OAuth (Advanced settings → Managed OAuth) и установите Allowed redirect URIs на фактический callback вашего коннектора — для Claude/Cowork это https://claude.ai/api/mcp/auth_callback. Публичные HTTPS-callback обязательно должны быть указаны, иначе Dynamic Client Registration завершится с ошибкой invalid_client_metadata: redirect_uri is not allowed by the account configuration; loopback (http://localhost:*) callback разрешены по умолчанию.

   • Скопируйте AUD-тег приложения → он станет CF_ACCESS_AUD.

2. Выделите /mcp обратно с помощью второго приложения Bypass, ограниченного путём. Поскольку шаг 1 покрывает весь хост, /mcp (принесите свой ключ) теперь тоже закрыт. Создайте ещё одно самостоятельно размещённое приложение, домен plausible-mcp.sentry.dev путь mcp, с Managed OAuth OFF и политикой, чьё действие — Bypass с селектором Everyone.

   • Bypass ≠ Allow: политика Allow всё равно принуждает к интерактивному входу (клиент получает HTML 302 на страницу входа и завершается с ошибкой Unexpected content type: text/html). Только Bypass пропускает запрос без аутентификации, поэтому применяется собственная проверка Bearer-ключа Worker.

3. Установите секреты Worker:

   npx wrangler secret put PLAUSIBLE_API_KEY          # shared key for /internal queries
   npx wrangler secret put SENTRY_DSN                 # optional — the Worker's own telemetry

   CF_ACCESS_TEAM_DOMAIN и CF_ACCESS_AUD — не секреты — публичный URL JWKS и идентификатор приложения — поэтому они помещаются в [vars] на шаге 4.

4. Установите [vars] в wrangler.toml:

   • CF_ACCESS_TEAM_DOMAIN — https://<team>.cloudflareaccess.com, без завершающего слэша. Проверяет JWKS и издателя Cf-Access-Jwt-Assertion.

   • CF_ACCESS_AUD — AUD-тег, скопированный на шаге 1.

   • ALLOWED_EMAIL_DOMAIN — домен(ы) электронной почты, которым разрешён вход, через запятую, @ необязателен (по умолчанию sentry.io). Применяется в коде в дополнение к политике Access на шаге 1, поэтому установите свой домен — иначе каждый вход будет отклонён.

   • MCP_ALLOWED_HOSTNAMES — разделённые запятыми имена хостов, принимаемые MCP-эндпоинтами. Замените plausible-mcp.sentry.dev на хост вашего Worker; сохраните записи localhost, если используете wrangler dev.

   • MCP_ALLOWED_ORIGIN_HOSTNAMES — разделённые запятыми имена хостов браузерного Origin, которым разрешено вызывать /internal. Небраузерные клиенты не отправляют заголовок Origin.

5. Разверните (npx wrangler deploy), затем укажите MCP-клиенту с поддержкой RFC 8707 на https://<your-worker-host>/internal.

Устранение неполадок. Всё это — конфигурация Cloudflare Access, а не Worker — запрос достигает Worker (и его Sentry-спанов) только после того, как Access перешлёт его:

Конфигурация

На Worker конечной точке /mcp не нужен серверный ключ — каждый пользователь передаёт свой через Authorization: Bearer. Конечная точка /internal защищена Cloudflare Access Managed OAuth и использует общий серверный секрет PLAUSIBLE_API_KEY (см. self-hosting).

Plausible API

Этот сервер оборачивает Plausible Stats API v2 (POST /api/v2/query). Он работает как с Plausible Cloud, так и с self-hosted экземплярами.

Поддерживаемые метрики

visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events, scroll_depth, percentage, conversion_rate, group_conversion_rate, average_revenue, total_revenue, time_on_page

Поддерживаемые измерения

event:page, event:goal, event:hostname, visit:entry_page, visit:exit_page, visit:source, visit:referrer, visit:channel, visit:utm_medium, visit:utm_source, visit:utm_campaign, visit:utm_content, visit:utm_term, visit:device, visit:browser, visit:browser_version, visit:os, visit:os_version, visit:country, visit:region, visit:city, visit:country_name, visit:region_name, visit:city_name

Географические измерения *_name возвращают человекочитаемые названия (например, «Канада»); обычные visit:country/region/city возвращают коды ISO/Geoname.

Фильтрация

Каждый инструмент запроса принимает property_filters, который — несмотря на название — фильтрует как по встроенным измерениям, так и по пользовательским свойствам событий. Каждая запись — { "property", "operator", "values" }:

• property — встроенное измерение (например, visit:channel, visit:source, event:page) или пользовательское свойство по его имени без префикса ("plan" обращается к event:props:plan).

• operator — is, is_not, contains, contains_not (по умолчанию is). event:goal поддерживает только is и contains.

• Несколько записей объединяются по AND, как и параметры-сокращения page/goal. Обращение к event:page/event:goal одновременно через сокращение и property_filters в одном вызове отклоняется — используйте что-то одно.

Например, топ страниц по органическому поисковому трафику: get_breakdown с dimension: "event:page" и property_filters: [{ "property": "visit:channel", "values": ["Organic Search"] }].

Пользовательские свойства

Сайты отправляют свои пользовательские свойства событий, адресуемые как event:props:<name>. Они специфичны для сайта, поэтому фиксированного списка нет.

• Разбивка по пользовательскому свойству: передайте get_breakdown dimension вида event:props:<name> (например, event:props:plan).

• Фильтрация по пользовательскому свойству через property_filters с именем без префикса, например [{ "property": "plan", "operator": "is", "values": ["pro"] }].

Разработка

pnpm install
pnpm build         # TypeScript compilation
pnpm test          # Run unit + integration tests
pnpm test:watch    # Watch mode

Тестирование с MCP Inspector

pnpm build
PLAUSIBLE_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

LLM-оценки

Проверяет, что модель выбирает правильный инструмент для вопросов по аналитике на естественном языке. Запускается через OpenRouter, поэтому подходит любая модель с поддержкой вызова инструментов — по умолчанию anthropic/claude-sonnet-5:

OPENROUTER_API_KEY=sk-or-... pnpm eval
OPENROUTER_MODEL=openai/gpt-5 OPENROUTER_API_KEY=sk-or-... pnpm eval  # try another model

Архитектура

src/
├── index.ts              # STDIO entry point (local use)
├── worker.ts             # Cloudflare Worker entry point (remote)
├── env.ts                # Worker environment bindings
├── cf-access.ts          # Verifies the Cloudflare Access assertion on /internal
├── server.ts             # Creates McpServer, registers all tools
├── plausible.ts          # PlausibleClient — standalone API client
├── schemas.ts            # Shared Zod schemas and filter helpers
├── errors.ts             # UserFacingError and tool-error reporting
├── telemetry.ts          # Pure classifiers — route, MCP request kind, client family
├── mcp-telemetry.ts      # Records MCP client info onto the active span
├── redaction.ts          # Strips PII from Sentry events on the BYOK path
└── tools/
    ├── get-timeseries.ts
    ├── get-breakdown.ts
    ├── get-conversions.ts
    ├── compare-periods.ts
    └── send-feedback.ts

PlausibleClient не имеет зависимостей от MCP и может использоваться автономно.

Наблюдаемость и сбор данных

Worker отправляет отчёты в Sentry с режимом конфиденциальности, зависящим от конечной точки:

• /mcp (bring-your-own-key) — полностью анонимный. Входные и выходные данные инструментов не записываются (эти данные принадлежат вызывающему и его собственному ключу), личность не привязывается, а определённый при приёме IP клиента удаляется (src/redaction.ts). Остаётся только операционная телеметрия: имена инструментов, тайминги спанов и сбои.

• /internal (за SSO) — атрибутированный. Запросы несут аутентифицированный email @sentry.io (Sentry.setUser), а входные/выходные данные инструментов записываются (recordToolIO) для атрибуции и отслеживания злоупотреблений на общем серверном ключе.

Заголовки Authorization / Cookie / Cf-Access-Jwt-Assertion удаляются из спанов на обоих путях. В качестве дополнительной страховки включите Prevent Storing of IP Addresses в настройках Security & Privacy проекта Sentry.

Лицензия

MIT — см. LICENSE.