Vitrus analytics MCP server
2026년 10월 23일 커밋검증 가능한 SQL 근거를 바탕으로 웹 및 모바일 앱의 트래픽, 사용자, 리텐션, 매출에 대해 AI 클라이언트가 읽기 전용 분석을 수행할 수 있도록 지원합니다.
다른 이름 Vitrus-Dev/vitrus, vitrus
- 스타
- 6
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 0.11.1
- 마지막 커밋
- 2026년 10월 23일
- 라이선스
- Apache-2.0
Vitrus analytics MCP란?
검증 가능한 SQL 근거를 바탕으로 웹 및 모바일 앱의 트래픽, 사용자, 리텐션, 매출에 대해 AI 클라이언트가 읽기 전용 분석을 수행할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
Vitrus analytics MCP server 정보
Vitrus analytics는 AI 클라이언트를 통해 웹 및 모바일 애플리케이션의 성능을 모니터링할 수 있는 읽기 전용 인터페이스를 제공합니다. iOS, Android, 웹 플랫폼 전반에 걸쳐 사용자 트래픽, 리텐션, 매출, Web Vitals를 포함한 핵심 지표를 추적합니다. 이 시스템은 개인정보 보호를 위해 설계되었으며, 해싱된 식별자를 사용하여 이메일과 같은 원본 사용자 데이터가 서버에 도달하지 않도록 합니다. 개발자는 Bun을 사용하여 셀프 호스팅 프로세스로 배포하거나 호스팅된 클라우드 버전을 사용할 수 있습니다.
사용자는 MCP 엔드포인트를 사용하여 Claude, ChatGPT, Cursor와 같은 AI 어시스턴트를 연결합니다. 이 서버는 데이터를 가져오기 위해 get_portfolio, get_lifecycle, get_revenue를 포함한 17개의 특화된 도구를 제공합니다. 핵심 기능은 검증 가능한 근거 시스템으로, AI에 반환되는 모든 지표에는 이를 생성하는 데 사용된 특정 SQL 쿼리가 포함됩니다. 이를 통해 AI는 출처를 인용할 수 있으며 데이터에 대해 검증되지 않은 주장을 하는 것을 방지합니다.
활용 사례
- 1주간 성능 요약 생성AI 어시스턴트에게 채널 성능을 포함하여 지난주 지표와 전주 지표를 비교하는 보고서를 작성하도록 요청하세요.
- 2갑작스러운 트래픽 감소 조사지표가 정확히 언제 하락했는지 식별하고, 이것이 오류나 Web Vitals의 변화와 상관관계가 있는지 확인하세요.
- 3AI 기반 트래픽 패턴 감사표준 웹 크롤러와 비교하여 AI 어시스턴트를 통해 유입되는 사용자가 얼마나 되는지 비교하세요.
- 4멀티 앱 포트폴리오 분석보유한 모든 애플리케이션의 활성 사용자 및 매출에 대한 나란히 비교(side-by-side comparison)를 요청하세요.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Vitrus analytics MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Vitrus analytics MCP 설치
$ claude mcp add --transport http vitrus https://app.vitrus.dev/mcpCursor에 Vitrus analytics MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"vitrus": {
"url": "https://app.vitrus.dev/mcp"
}
}
}VS Code에 Vitrus analytics MCP 설치
.vscode/mcp.json
{
"servers": {
"vitrus": {
"type": "http",
"url": "https://app.vitrus.dev/mcp"
}
}
}VS Code CLI에 Vitrus analytics MCP 설치
$ code --add-mcp '{"name":"vitrus","type":"http","url":"https://app.vitrus.dev/mcp"}'Codex에 Vitrus analytics MCP 설치
$ codex mcp add vitrus --url https://app.vitrus.dev/mcpCodex config.toml에 Vitrus analytics MCP 설치
~/.codex/config.toml
[mcp_servers.vitrus] url = "https://app.vitrus.dev/mcp"
Gemini CLI에 Vitrus analytics MCP 설치
$ gemini mcp add -s user --transport http vitrus https://app.vitrus.dev/mcpGemini settings.json에 Vitrus analytics MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"vitrus": {
"url": "https://app.vitrus.dev/mcp",
"type": "http"
}
}
}구성
VITRUS_PASSWORD
| 이름 | 설명 | 유형 |
|---|---|---|
| VITRUS_PASSWORD | — |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능vitrus-dev/vitrus is public and reachablegithub.com/vitrus-dev/vitrus ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-23github.com/vitrus-dev/vitrus ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답HTTPS endpoint answered 401 (sign-in required)통과
README
GitHub에서 보기Quickstart
You need Bun 1.3 or newer. That is the whole list.
bun install -g @vitrus-dev/cli
vitrus init # creates ./vitrus.db and a secret salt
vitrus site add "My site" example.com # prints your script tag
VITRUS_PASSWORD="a long secret" vitrus start # ingest + dashboard on http://localhost:3000
From source instead: git clone https://github.com/Vitrus-Dev/vitrus && cd vitrus && bun install && bun run build:tracker,
then run bun packages/cli/src/cli.ts wherever this says vitrus.
Then one line in your site's <head>:
<script defer data-site="SITE_ID" src="https://YOUR-HOST/v.js"></script>
Mobile apps: Vitrus for Swift (iOS, iPadOS, macOS — Swift Package Manager) and Vitrus for Flutter & Dart. Same panel, user ids hashed on the device, no device identifier.
No Docker Compose file, no database server, no migration step. Rather not run it? app.vitrus.dev is the same engine, hosted, with a free plan — and the live demo opens the full hosted dashboard on sample data, no account needed.
Every number opens the query that made it
Click a figure and you get the SQL that ran, its parameters, the window and the result — not a description of the number, the number's origin. It is the same evidence the AI summary is checked against.
That matters more now that models write the reports. When an AI-written sentence contains a number that is not in the evidence, Vitrus drops the sentence before it reaches you:
Visitors are down 18% against the previous period. [e1]
The drop coincides with the last deploy. [e1, e7]
✗ dropped: "The new theme caused a 41.7% fall in conversion."
→ 41.7 is in no evidence record, and "caused" is a claim nobody can make from this data.
Every app you ship, one panel
Shipping several apps — web and mobile — usually means one admin page per app just to see who signed up. Add one line where your app knows the user is signed in, and Vitrus counts who is new, who came back, who you lost and who started paying, per app and for all of them side by side:
vitrus.identify(user.id) // required: hashed in the browser, never sent raw
vitrus("signup") // optional
vitrus("plan", { plan: "pro" }) // optional: your own plan labels
- Every user, under a made-up name. Open an app and each signed-in user is a row — returning, one-time or signed up only, actions, active days, visits, joined, last active; opened, actions by day and recent visits — shown as "Amber Falcon · 3f9a2c", because no email or name is stored to show.
- Lifecycle per app. New, active, came back, lost, net, quick ratio, one-and-done, current plans, became and stopped paying — each with its query.
- Ask your AI. "Which of my apps lost the most users this week?" —
get_portfolioandget_lifecycleover MCP answer with counts and the queries behind them. - Hashed before it leaves the browser. The script sends
sha256(site + "|" + id); the server hashes that again with a secret before storing it. Your users' ids — often emails — never reach the server. No WebCrypto, no id sent. - Separate per app, by design. The same person in two of your apps is two unrelated hashes; nobody can join them. Portfolio totals say so instead of pretending to deduplicate.
- Personal fields dropped twice. Email, phone, name, address, password, token and similar properties — and any value shaped like an email or phone number — are removed in the browser and again on the server, and the removal is counted.
- No auth provider to connect. Works the same with Supabase, Clerk, Firebase, Better Auth or your own login.
Self-hosted: GET /api/people?site=…, GET /api/lifecycle?site=… and GET /api/portfolio on your server; over MCP, get_lifecycle and
get_portfolio. How it is counted →
A whole analytics product
Screenshots: the hosted dashboard on a demo workspace; every figure is sample data — open it yourself. The self-hosted dashboard in this repository is simpler today — see Architecture for exactly which views it renders.
Ask your AI about your analytics
Vitrus speaks MCP. Your assistant reads your analytics — read-only — and every number it gets back comes
with the query that produced it, so it can cite instead of assert. Listed in the official
MCP Registry as dev.vitrus/analytics.
| Where | How |
|---|---|
| ChatGPT · Claude (web & desktop) | Add a custom connector with https://app.vitrus.dev/mcp, sign in, pick a workspace, Allow. |
| Claude Code — plugin with 4 skills | claude plugin marketplace add Vitrus-Dev/vitrus then claude plugin install vitrus@vitrus |
| Claude Code — server only | claude mcp add vitrus --transport http https://app.vitrus.dev/mcp |
| Cursor | |
| Gemini CLI | gemini extensions install https://github.com/Vitrus-Dev/vitrus |
| Anything else | {"type": "http", "url": "https://app.vitrus.dev/mcp"} — OAuth, or Authorization: Bearer vk_… (a workspace API key) |
The plugin's skills, under plugins/vitrus/skills:
/vitrus:weekly-report— last week against the week before, channels, AI assistants, goals; every figure cited./vitrus:traffic-drop— finds the day a number broke and the segment it lives in, then checks errors and Web Vitals./vitrus:measurement-plan— reads your code and proposes the events, goals, funnels and revenue calls to add./vitrus:ai-search-audit— which assistants send people, which pages the AI crawlers read, and where the two disagree.
17 tools, all read-only: query_stats (any metric by any of 20 dimensions or by day, with filters),
get_portfolio (all your apps side by side), get_lifecycle, get_realtime, get_ai_traffic, get_revenue,
goal_report, analyze_funnel, get_journeys, get_retention, get_web_vitals, get_errors, get_digest and more — docs.
Connections are scoped to one workspace and can be disconnected any time under Account → Connected apps.
What it is, in one paragraph
Vitrus tells you how many people visit your website, where they come from, what they do and where they leave. It sets no cookies, so you do not need a consent banner. Use the hosted version at vitrus.dev or run it yourself as a single program — there is no database server to install.
Features
- The query behind every number. Every metric travels as
{ id, sql, params, window, value }, and the dashboard opens that exact SQL when you click the badge beside a figure. - AI summaries that cannot invent. Numbers come from deterministic SQL first. The optional model (local Ollama, or your own key — neither is on by default) may rephrase them and may not produce one; a numeric guard drops any sentence it cannot support, and a golden-set eval holds leaks at 0.
- AI referrals ≠ AI crawlers.
chatgpt.comsending a person andGPTBotreading a page are two different events, classified separately and never summed — by a versioned rule table held at 100% precision and recall by its own eval. - Which pages the crawlers read, per page — the feedback loop GEO/AEO work actually needs.
- Verified agent identity. A request signed with Web Bot Auth (RFC 9421 HTTP Message Signatures) is checked against the Ed25519 key its operator publishes, so the signer can be named. A user-agent is a sentence; a signature is proof.
- Agent sessions as their own class — kept out of your visitor numbers, reported separately, never silently dropped or counted as people.
- Two-layer bot detection, in the open-source core. A user-agent table plus header rules that check whether a request agrees with the browser it claims to be. Recorded and shown, never self-applying: a suspicion is not a verdict.
- Everything else you expect — pageviews, sessions, unique and live visitors, bounce rate, visit duration, top / entry / exit pages, referrers, channels, UTM campaigns, devices, browsers, OS, screens, languages, country, custom events with properties, outbound clicks, form submissions, field-level form abandonment, rage and dead clicks, scroll depth, ordered funnels, retention cohorts, Core Web Vitals at p75 and JavaScript errors.
- Session replay, opt-in and masked. Off until you switch it on for a site, loaded as a
separate script only on pages that carry
data-replay, and every text node and input value masked by default. Password, card and one-time-code fields are always blocked. Recordings play in a sandboxed player in the self-hosted dashboard. - City, region and coordinates without a GeoIP database — read from the headers your proxy already sets (Cloudflare, Vercel, CloudFront), coordinates rounded to 0.1°.
- Digests: what happened → why → what to do.
vitrus digestwrites one in your terminal, every line tagged with the evidence ids behind it. The Slack / email / webhook channels and the never-sent-twice scheduler ship in the core. - A read-only MCP server with 17 tools — any metric by any dimension, every app side by side, user lifecycle,
real-time, AI traffic, revenue, goals, funnels, journeys, retention, vitals, errors — that returns the evidence with every number, so
an agent can cite instead of assert. On the cloud, ChatGPT and Claude connect with OAuth (add
https://app.vitrus.dev/mcp, sign in, pick a workspace); Claude Code is one line:claude mcp add vitrus --transport http https://app.vitrus.dev/mcp. - Private by construction. No cookies, no stored identifier, no fingerprinting, no consent banner. Do Not Track honoured by default. A 3.0 KB tracker. Zero runtime dependencies, enforced by CI.
Deliberately absent: ad-platform attribution (ROAS/CPA) and multi-touch attribution models, because a model's opinion is not something we can prove.
Self-hosting, in more detail
The Quickstart is the whole install. Set VITRUS_PASSWORD before the port is reachable
from outside: the dashboard and the read API then ask for it (HTTP Basic, any user name), while the
tracker and ingest stay public because your visitors' browsers call them. Without it, vitrus start
prints a warning and anyone who can reach the port can read your analytics.
Want data on screen straight away? vitrus demo <site-id> generates a realistic week of sample traffic.
vitrus site ls # list your sites
vitrus digest <site-id> --days 7 # deterministic summary, in your terminal
vitrus digest <site-id> --llm ollama:gemma3:4b # phrased by a local model; data never leaves the box
vitrus start --port 8080
The database path is VITRUS_DB (default ./vitrus.db). Put Cloudflare, Vercel, Fly, CloudFront or
Netlify in front and country (and, from Cloudflare, Vercel or CloudFront, region and city) is read from
the headers they already set — there is no GeoIP database
to download, and without a proxy the dashboard says the data is missing rather than guessing.
How it compares
The open-source alternatives are good, and several do things we do not. This table lists only differences we can state without qualification. Checked 24 September 2026 against each product's own documentation — if a cell is out of date, please open an issue.
| GA4 | Plausible | Umami | Rybbit | Vitrus | |
|---|---|---|---|---|---|
| Open source | ✗ | ✓ AGPL-3.0 | ✓ MIT | ✓ AGPL-3.0 | ✓ Apache-2.0 |
| Cookie-free, no consent banner | ✗ | ✓ | ✓ | ✓ | ✓ |
| Services to install | — | Postgres + ClickHouse | Postgres or MySQL | Postgres + ClickHouse | none (one SQLite file) |
| Tracker size (gzipped) | ~28 KB | ~1 KB | ~2 KB | ~18 KB | 3.0 KB |
| AI assistants as a channel | ✗ | ✓ | ✓ | ✓ | ✓ |
| Crawler reads separated from the humans they send | ✗ | ✗ | ✗ | ✓ | ✓ |
| The query behind every number, in the UI | ✗ | ✗ | ✗ | ✗ | ✓ |
| AI sentences dropped when the number is unprovable | ✗ | ✗ | ✗ | ✗ | ✓ |
| Verified agent identity (Web Bot Auth) | ✗ | ✗ | ✗ | ✗ | ✓ |
| Bot detection beyond the user-agent, in the open-source build | ✗ | ✗ | ✗ | ✗ | ✓ |
| Funnels, journeys and goals | ✓ | ✓ (funnels on paid plans) | ✓ | ✓ | ✓ |
| Session replay | ✗ | ✗ | ✓ | ✓ | opt-in, masked by default |
| Public API with keys | ✓ | ✓ | ✓ | ✓ | ✓ read-only |
| City-level geography | ✓ | ✓ | ✓ | ✓ | from proxy headers |
| Hundreds of millions of events a month | ✓ | ✓ | ✓ | ✓ | ~1M/month per box |
Where Vitrus is ahead
- You can check every number. Click it and you get the query, its parameters and the rows. No other tool in this table does that.
- AI summaries cannot make numbers up. A sentence whose number is not in the evidence is removed.
- AI traffic, told apart properly. Visitors that ChatGPT or Perplexity sent you are one thing; the AI crawlers reading your pages are another; agents that sign their requests are verified and named.
- Nothing to operate. One process and one SQLite file (built into the Bun runtime). The others need a database server — Postgres or MySQL, and for two of them ClickHouse as well.
- The privacy default is the strict one. The visitor id is re-salted every day, always.
Where others are ahead
- Heatmaps — Umami has them; we do not.
- Importing your history — we import from Umami only; Plausible imports Google Analytics history, and Rybbit imports Plausible exports too.
- Maturity and scale. Replay, autocapture of every button click and hundreds of millions of events a month are all further along in Rybbit and Umami, which run on ClickHouse or Postgres. Our embedded database is what makes the zero-service install possible, and it is also its ceiling (about a million events a month per box).
- Ad attribution. If your reporting is tied to Google or Meta ad spend, GA4 closes that loop and we never will.
- Cities without a proxy. Everyone else bundles a GeoIP database; we read city and region from Cloudflare, Vercel or CloudFront headers, and show only the country otherwise.
One-page write-ups per tool: vitrus.dev/compare.
Privacy
The visitor id is a one-way hash that cannot follow anyone across days:
sha256(secret_salt | day | site | ip_prefix | user_agent)
The salt rotates daily, the IP is never stored (IPv6 is reduced to its /64 first), and nothing is
written to the browser. That is also why the retention page tells you when it cannot compute a
cohort instead of showing zeros — call vitrus.identify(user.id) for signed-in users and retention
becomes real, with the raw id never touching disk.
Architecture
packages/
core ingest · classifiers · MetricBundle · numeric guard · digest · agent verifier ·
explore queries (sessions, users, journeys, goals, geo) · replay ingest + player
tracker the browser script, 3.0 KB gzipped (+ an opt-in replay recorder, under 5 KB)
server one process: ingest + query API + tracker + evidence dashboard
cli init · site · start · digest · demo
mcp read-only MCP module (JSON-RPC over HTTP) for AI agents
Every package has zero runtime dependencies. The SQL string is the evidence — Store.select
takes raw SQL on purpose, because hiding it behind an ORM would remove the one thing this project is
for.
A few pieces ship in the core as libraries before the self-hosted server exposes them. Today the
server does not yet mount the MCP module, run the scheduled digest delivery, accept server-side
forwarded requests (which is how signed agents and non-rendering crawlers are seen — a browser script
never sees them), take row filters, or render the sessions, users, journeys, goals and globe views; the building blocks are here and wiring them into vitrus start is on the
roadmap.
Running the gates
bun install && bun run build:tracker
bun run gates
Type checks, the test suites, two golden-set evals and the build gates:
| Gate | What it prevents |
|---|---|
eval:referrer |
the AI-source table going stale unnoticed — 100% required |
eval:insight |
an unprovable number surviving into prose — zero leaks tolerated |
gate:core-purity |
the metric layer ever importing the LLM layer |
gate:no-deps |
a runtime dependency appearing without a deliberate decision |
gate:tracker-size |
the tracker quietly growing past 3 KB |
gate:inline-js |
a bad escape killing the dashboard's script while the page still renders |
Cloud
app.vitrus.dev is the hosted version: teams and roles, quotas, EU
hosting and digest delivery without running your own mail provider, plus the sessions, users,
journeys, goals, real-time and globe views. The analysis engine is the same: every query those views
run lives in packages/core in this repository.
Community
- Questions and ideas — GitHub Discussions
- Bugs — open an issue. A failing case beats a description; the AI referrer table in particular is tested by example.
- Security — see SECURITY.md. Please do not open a public issue for a vulnerability.
- Contributing — see CONTRIBUTING.md. The most useful first contribution is a new AI-referrer rule with the test case that pins it.
Star history
Contributors
License
Vitrus analytics MCP 질문
Vitrus analytics MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --transport http vitrus https://app.vitrus.dev/mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Vitrus analytics MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
분석 데이터에 대해 AI에게 무엇을 물어볼 수 있나요?
'이번 주에 사용자 이탈이 가장 많은 앱은 무엇인가요?'와 같은 질문을 할 수 있으며, AI는 수치와 함께 기반이 되는 SQL 쿼리를 사용하여 답변합니다.
Vitrus는 사용자 개인정보를 어떻게 처리하나요?
사용자 ID는 전송 전 기기에서 해싱되며, 이메일이나 전화번호와 같은 개인 정보 필드는 브라우저와 서버 모두에서 제거됩니다.
AI가 데이터에 대해 잘못된 주장을 할 수 있나요?
아니요, Vitrus는 기반 SQL 근거로 뒷받침되지 않는 숫자가 포함된 AI 생성 문장은 모두 삭제합니다.