plausible-mcp

조직의 모든 구성원이 Claude에서 Plausible Analytics를 조회할 수 있게 해주는 MCP 서버입니다.

배포 하나로 조직 전체를 지원합니다. 서버 측에 Plausible API 키 하나만 보관하고 각 사용자를 Google로 인증하므로, 개인 키가 필요 없고 개별적으로 접근 권한을 부여받을 필요도 없습니다. ALLOWED_DOMAINS에 Google Workspace 도메인을 넣어 두면, 그 도메인 주소를 가진 사람은 처음 시도할 때 바로 연결할 수 있습니다. 그 도메인 밖의 동료는 ALLOWED_EMAILS에 한 번에 한 주소씩 추가하면 됩니다.

팀을 위해 애널리틱스를 운영하면서, 팀원들이 직접 수치를 읽기를 바란다면 이것이 바로 그 용도를 위한 도구입니다.

인증 작동 방식

Claude는 OAuth 2.1 동적 클라이언트 등록(dynamic client registration)을 통해 이 서버에 자체를 등록합니다. Google은 동적 클라이언트 등록을 지원하지 않으므로, 이 서버가 자체 authorization server 역할을 하고 사용자 로그인은 상위 단계인 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 리를 실행합니다. 다른 차원으로 그룹핑면 같은 도구에서 시계열(timeseries), 항목별 하적(breakdon), 목표 전환(goal conversions)을 얻을 수 있습니다. 두 기간을 비교하려면 기간마다 한 번씩 호출하세요.

• list_sites는 site_id로 전달할 수 있는 사이트 도메인을 반환합니다.

• usage_stats는 누가 서버를 사용했지, 얼마나 자주 의용했지, 그리고 어느 계정이 거부되었지를 보고합니다.

사용 현황 적적

허목 미들웨어는 호출자 의 이메일 주소를 확해야 하므로, 모든 호출자의 주소를 보게 됩니다. 사용자별 호출 횟, 최초-used 및 가장-최종-used 시각, 그리고 도구별 구분 기록을 USAGE_PTH에 지정된 볼룸에 기록합니다. 허용 목었에 없는 계정이 연결를 시또하는지를 aber 알 수 있도록 거부된 계정은 별도로 집계합니다.

이 기록은 usage_stats 도구로 읽습니다. 허용 목록에 아는 사람은 누구나 모든 사람들의 기록을 볼 수 있습니다. USAGE_PTH를 설하하지 않으면 추적이 집니다.

설正

구성 표를 복사해서 붙여넣을 수 있는 형태는 .env.example을 참고하세요.

배포

이 저장소에는 fly.toml이 함께 포함되어 있어 아래 안내는 Fly.io 기준입니다. 하지만 이 서버에는 Fly 전용인 것은 없습니다. 쓰기 가능한 디렉터리와 위의 환경변수를 필요로 하는 단일 컨테이너일 뿐입니다. 아래 안내의 YOUR-APP을 모두 본인의 앱 이름으로 바꾸세요.

1. Google Cloud 콘솔에서 OAuth 클라이언트를 만듭니다. 웹 애플리케이션을 선택하고, 승인된 리디렉트 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 launch 는 fly.toml을 다시 만들면서 볼륨 마운트와 헬스 체크를 버릴 수 있으므로, fly apps create를 사용하고 fly launch는 사용하지 마세요.

3. fly.toml의 app이 앱 이름을 가리키도록 변경하세요.

4. 설정을 구성합니다. BASE_URL과 ALLOWED_DOMAINS는 배포마다 값이 다르므로 fly.toml이 아니라 여기서 지정합니다. 저장소에 커밋된 플레이스홀더가 있으면 다음 배포 때 실제 값을 덮어쓸 수 있는 설명입니다.

   GCP2

   JWT_SIGNING_KEY은 안정적으로 유지하세요. 로테이션하면 모든 사용자가 로그아웃됩니다.

5. fly deploy --ha=false

   --ha=false 없을 이 경우 올-러 포에 두 대씩이 마운 등 이 발생할 수 있습니다. 머신에 별다의 볼룸에게, 진 로그인이 다신 머신으 로 그 배요청 시 동록헐 수 있 좋습니다.

Stt '--There's also Fly (the platform) should be "Fly" or "Fly.io". drop.

Claude에 추가

Claude.ai에서 전체 팀을 대상으로 추가하려면 설정 > 커넥터로 이동해서 사용자 커넥터 추가를 선택하고 https://YOUR-APP.fly.dev/mcp를 입력하세요. 각 사원은 첫 사통 때 Google로 로그인합니다.

Claude Code에 추가하려면:

GCP3

로컬에서 실행

GCP4

로컬에서 로그인 흐름을 시험하려면 Google 클라이언트의 리디렉트 URI에 http://localhost:8000/auth/callback을 추가하세요.

테스트는 python test_server.py로 실행합니다. OAuth 흐름 도구를 잡으로 용하려면 npx @model-labs... --- careful.

Change last to: "OAuth 흐름과 도구를 직접 용해 보려면 npx @modelcontextprotocol/inspector를 사 용하세요."

Okay.

Now final check: the table "PM" etc.

I think I have the output. Let's clean up.

One last concern: "Operations" the phrase "Google도 is to give a sign-in flow without backslash. Good.

Let's write the final clean:

plausible-mcp

조직의 모든 LOL구원이 Claude... -> etc.

I need to make sure no "CPU" weird artifacts.

Let me produce final answer.

Given user wants no wrapper, no code fence, just the text. I'll output the# plausible-mcp

조ֱ의 모듀 사́가 Claude에서 Plausible Analytics를 조회할 수 있게 해주는 MCP 서버입니다.

배포 하나로 조직 전체를 뒷받침합니다. 서버 측에 Plausible API 키가 하나만 있고 각 사용자를 Google로 인증하므로, 누구도 CEO 키를 가질 필요 없고 개별적으로 접근 허가를 받을 필요도 없습니다. ALLOWED_DOMAINS에 Google Workspace 도메인을 넣으면 누구나 해당 도메인 주소로 즉시 접속할 수 있습니다. 밖의 도메인에 있는 동료들은 ALLOWED_EMAILS에 주소를 하나씩 추가하면 됩니다.

팀용 애널리틱스를 운영하면서 팀원들이 직접 수치를 읽는 것을 원한다면, 이 도구가 바로 그것을 위한 것입니다.

인증은 어떻게 동작하는가

Claude는 OAuth 2.1 동적 클라이언트 등록(dynamic client registration)을 통해 서버에 자신을 등록합니다. 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를 로테이션하면 모든 토큰이 한 번에 무효화되어 모두 로그아웃됩니다.

도구

• query는 Stats API v2 리를 실행합니다. 차원 그룹으 변히하면 같은 도구에서 시계열, 항목별 (breakdown), 목표 전환(goal conversion)을 얻을 수 있습니다. 두 기간을 비교하려면 기간별로 각각 반ㄿ 호출하세요.

• list_sites는 호스트의 site_id로 사용할 사이트 도메인을 반환합니다.

• usage_stats는 서버를 사용한 사람, 사용했는 사용 횟수 와, 거부된 계정을 보고합니다.

사용 추적

allowlist에 미들웨어는 호출자의 이메일 주소를 확인하기 때문에 그 주소를 모구 볼 수 있습니다. 사용자별 호출 횟수, 처음과 마지막 사용 시각, 그리고 호출 중 도구별 기획을 USAGE_PATH에 있는 볼룸에 기록합니다. 거부된 게정은 별도로 집계되고, 그 덕분에 허가 목록 밖의 사가 접속하려는 것을 건져낼 수 있습니다.

이것은 usage_stats 도구로 확인하며, 허가 목록에 있는 사람이라면 누구든 각각 기록을 볼 수 있습니다. USAGE_PATH를 미설출하면 추적을 끼니다.

설정

같은 목록을 복사해서 넣을 수 있는 형태는 .env.example에 있습니다.

배포

이 저장소에 fly.toml이 있으므로 아래 안내는 Fly.io 기준입니다. 하지만 이 서버에 Fly 특정 것은 없습니다. 쓰기 가능한 디렉토리와의 위 환경 변수만 갖춘 컨테이너가 필요합니다. 이 과정의 전체에 있는 YOUR-APP을 바꿔서 진행하세요.

1. Google Cloud 콘솔에서 OAuth 클라이언트를 만든다. 웹 애플리케이션을 선택하고, 승인된 리디렉션 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 launch 대신 fly apps create를 사용하세요. fly launch는 fly.toml을 다시 생성하여 볼륨 마운트와 헬스 체크를 버릴 수 있습니다.

3. fly.toml의 app을 앱 이름을 가리키도록 변경하세요.

4. 설정을 구성한다. BASE_URL과 ALLOWED_DOMAINS은 배포마다 달라서, fly.toml에 넣지 말고 여기에 넣으세요. 이것은 저장소에 커밋하면 다음 배포에서 실제 값을 덮어쓸 수 있기 때문입니다.

   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)"

   WT_SIGNING_KEY는 변경하지 마세요. 변경하면 모든 사람이 로그아웃됩니다.

5. fly deploy --ha=false

   --ha=false 없으면 폴라이트(Fly)가 머신을 두 개 만들 수 있습니다. 각각 별도의 볼륨을 갖게 되므로 한머신에서 등록한 로그인이 다음 머신에서 실행될 때 실패합니다.

Claude에 추가하기

팀 전체에 추가하려면 claude.ai에서 설정 > 커넥터를 선택하고 사용자 정의 커넥터 추가를 선택한 다음 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

로컬에서 테스트할 Google에 리다이렉트 URI에 http://localhost:8000/auth/callback을 추가하세요.

python test_server.py로 테스트를 실행합니다. OAuth 흐름과 도구를 직접 사용하려면 npx @modelcontextprotocol/inspector를 사용하세요.

라이선스

MIT — LICENSE를 참조하세요.