plausible-mcp

plausible-mcp

MCP-сервер, который позволяет любому сотруднику организации делать запросы к Plausible Analytics из Claude.

Одного развёртывания достаточно для всей организации. На сервере хранится один ключ Plausible API, а каждый человек проходит аутентификацию через Google, поэтому никому не нужен собственный ключ, и никого не нужно добавлять вручную. Просто укажите домен Google Workspace в ALLOWED_DOMAINS — и любой обладатель адреса в этом домене сможет подключиться с первой попытки. Сотрудников из другого домена добавляйте в ALLOWED_EMAILS, по одному адресу.

Если вы ведёте аналитику для команды и хотите, чтобы люди сами читали числа, а не спрашивали их у вас, — это именно то, для чего сделан сервер.

Как работает аутентификация

Claude регистрируется на этом сервере с помощью динамической регистрации клиентов OAuth 2.1. Google не поддерживает динамическую регистрацию клиентов, поэтому сервер выступает как собственный сервер авторизации и делегирует вход человека в Google.

Google устанавливает, кто этот человек. Но Google не решает, может ли он читать вашу аналитику. Промежуточный слой при каждом вызове инструмента проверяет подтверждённый адрес электронной почты пользователя по ALLOWED_DOMAINS и ALLOWED_EMAILS. Если не задано ни то, ни другое, сервер отказывается запускаться.

ALLOWED_DOMAINS — это та часть, которая делает сервер доступным для всей организации: домен подтверждённого адреса должен совпадать точно, поэтому example.com допускает alice@example.com, но не alice@evil-example.com и не alice@example.com.evil.com.

Чтобы отозвать доступ у человека, удалите его из ALLOWED_EMAILS или ALLOWED_DOMAINS и переразверните сервер. Блокировка его аккаунта Google не даст ему снова войти, но список разрешений читает данные из токена, который подписал этот сервер, поэтому уже выданный токен продолжит работать до истечения срока. Ротация JWT_SIGNING_KEY делает все токены недействительными одновременно, но выводит всех из системы.

Related MCP server: Plausible MCP

Инструменты

• query выполняет запрос к Stats API v2. Группировка по разным измерениям даёт временные ряды, разбивки и конверсии целей через один и тот же инструмент. Чтобы сравнить два периода, вызовите его по разу для каждого периода.

• list_sites возвращает домены сайтов, которые можно передавать как site_id.

• usage_stats показывает, кто использовал сервер, как часто и каким учётным записям было отказано.

Отслеживание использования

Промежуточный слой со списком разрешений видит адрес почты каждого вызывающего, потому что обязан его проверять. Он записывает в том по пути USAGE_PATH число вызовов для каждого пользователя, время первого и последнего обращения, а также разбивку по инструментам. Отклонённые учётные записи учитываются отдельно — так вы видите, что кто-то вне списка пытается подключиться.

Читайте эти данные инструментом usage_stats. Любой, кто есть в списке разрешений, видит записи всех. Удалите USAGE_PATH, чтобы отключить отслеживание.

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

См. .env.example — там тот же список в удобном для копирования виде.

Развёртывание

В репозитории уже есть fly.toml, поэтому инструкции ниже приведены для Fly.io, но в сервере нет ничего специфичного для Fly: это один контейнер, которому нужна записываемая директория и переменные окружения выше. Замените YOUR-APP во всех местах.

1. Создайте OAuth-клиент в консоли Google Cloud. Выберите Web application и укажите разрешённый URI перенаправления https://YOUR-APP.fly.dev/auth/callback. URI должен совпадать точно.

2. Создайте приложение и его том:

   fly apps create YOUR-APP --org YOUR-ORG
   fly volumes create plausible_mcp_data --app YOUR-APP --region fra --size 1 --yes

   Используйте fly apps create, а не fly launch, потому что fly launch перезапишет fly.toml и потеряет подключение тома и проверку здоровья.

3. Укажите название вашего приложения в поле app в файле fly.toml.

4. Задайте конфигурацию. BASE_URL и ALLOWED_DOMAINS указываются здесь, а не в fly.toml, потому что они различаются между развёртываниями, а placeholder, попавший в репозиторий, перезапишет реальное значение при следующем деплое:

   fly secrets set --app YOUR-APP \
     BASE_URL=https://YOUR-APP.fly.dev \
     ALLOWED_DOMAINS=your-domain.org \
     GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com \
     GOOGLE_CLIENT_SECRET=GOCSPX-xxx \
     PLAUSIBLE_API_KEY=xxx \
     JWT_SIGNING_KEY="$(openssl rand -hex 32)"

   Не меняйте JWT_SIGNING_KEY без необходимости: его изменение выведет всех вне системы.

5. fly deploy --ha=false

   Без --ha=false Fly может запустить две машины. У каждой будет свой том, поэтому вход, выполненный на одной машине, не сработает при попадании следующего запроса на другую.

Подключение к Claude

Чтобы добавить сервер для всей команды, зайдите в Settings > Connectors в claude.ai, выберите Add custom connector и введите https://YOUR-APP.fly.dev/mcp. Каждый человек будет входить через Google при первом использовании.

Добавление для Claude Code:

claude mcp add --transport http plausible https://YOUR-APP.fly.dev/mcp

Локальный запуск

uv venv && uv pip install -r pyproject.toml
cp .env.example .env    # then fill it in
set -a && source .env && set +a
python server.py

Добавьте http://localhost:8000/auth/callback в список URI редиректа OAuth-клиента Google, чтобы протестировать локальный вход.

Запустите тесты через python test_server.py. Чтобы вручную проверить OAuth-поток и инструменты, используйте npx @modelcontextprotocol/inspector.

Лицензия

MIT — см. LICENSE.