
anacraft — Google Analytics 4
dev.anacraftv0.42.0更新于 Sep 30, 2026
Ask your Google Analytics 4 property how the site is doing: traffic, pages, events, audit.
概览
让助手读取 Google Analytics 4 媒体的流量、页面、事件、实时访客与审计结果,并为域名创建媒体资源和代码。
- 功能
- 通过 MCP 提供 GA4 数据,让助手回答网站表现相关问题。工具包括 site_status(与上一周期对比的核心指标)、audit_site(28 天内十六项测量检查)、live_visitors、list_pages、list_events、list_referrers、list_traffic_sources、list_countries、list_properties,以及按子串检索的 search_pages 和 search_events。configure_site 是唯一的写入工具:为域名创建媒体资源和网站数据流并返回要粘贴的代码。报告为结构化 JSON,带媒体资源 id 和日期范围。
- 适用场景
- 适合希望助手用你自己的 GA4 数据回答网站表现,或检查媒体资源测量是否正确,而无需打开仪表盘时使用。也适合在聊天客户端中创建新媒体资源并获取其代码。
- 运行要求
- 该服务器以本地命令 craft mcp 运行,由 MCP 客户端启动;清单中列有远程端点 app.anacraft.dev。需要 Google Analytics 4 媒体资源、事先执行 craft login 获得 OAuth 凭据,以及有效订阅(Elite 方案)。未登录或未订阅时服务器仍会启动,工具会说明缺少什么。可选环境变量包括 ANACRAFT_PROPERTY_ID、ANACRAFT_WEBHOOK、ANACRAFT_OAUTH_CLIENT_ID 和 ANACRAFT_OAUTH_CLIENT_SECRET。
安装
在 SourceWeft 中
- 打开 控制台中的 anacraft — Google Analytics 4,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
其他 MCP 客户端
把它添加到你客户端的 mcpServers 配置中。
{
"mcpServers": {
"google-analytics-ga4": {
"type": "http",
"url": "https://app.anacraft.dev/mcp"
}
}
}README
⛏ craft
Ask GA4 in plain English.
Connects your assistant to Google Analytics 4 through an MCP server, so you can ask how your site is doing and get the answer from your own numbers. Its dashboard at app.anacraft.dev creates the property and hands you the tag; the CLI audits what it is measuring so you can fix what is wrong, and reads it back as a terminal dashboard.
anacraft.dev · Releases · [License: Apache-2.0] [Rust 1.74+]
[The anacraft dashboard: seven panels showing GA4 metrics in a terminal]
craft dash --demo · osaka-jade · 132×52
Install
macOS / Linux
Installs to /usr/local/bin when that is writable, otherwise ~/.local/bin —
never with sudo. Set INSTALL_DIR to choose somewhere else:
From source
Manual — grab a binary from Releases, extract it, and put anacraft on your PATH.
Quick start
anacraft with no command opens the dashboard — dash is the default. With no
property saved it runs on synthetic data, so it works before you sign in.
No property yet? Sign in at app.anacraft.dev,
choose Create a new property and give it your site's URL. It creates the
property and its web data stream and hands you the gtag.js snippet with your
measurement id already in it, with a copy button — nothing to install. Paste it
into <head>, then craft use <id> here and craft live to watch the first
visit arrive. The dashboard is part of the
Anacrafter Elite plan ($9.99/month, the
same one craft mcp is on); the paywall comes before anything is created in
your Analytics account.
Give it a domain that already has a property and it creates nothing — it finds that property and hands its tag back — so doing it twice is how you get the tag again, not how you end up with two properties splitting your traffic.
Rather stay in the terminal? craft configure yoursite.com does the same thing
in one command, on the $2.99 Anacrafter plan,
and saves the property as the default. It asks Google for permission to write to
your Analytics account when you run it, never at sign-in; see
docs/oauth-scopes.md.
The dashboard, on your own machine
craft serve is the page at app.anacraft.dev, run locally — for when you would
rather your Google sign-in never left your machine, or want to script against
the same API.
It listens on 127.0.0.1 and nowhere else, mints a bearer token it prints once,
and answers a browser only from its own origin. The page is the first caller of
an API the whole of which is documented at
anacraft.dev/serve.html — so a script, an
editor extension or another service can register a tag the same way. It creates
the same property and stream the hosted dashboard does, through the same two
Admin API calls — and it can throw a property into Google's trash the way
craft delete --all does, asking for the id twice before it will.
It is part of the Anacrafter Elite plan,
the same one craft mcp is on, so one subscription covers the tag and the
assistant that reads the numbers afterwards. The command itself starts for
anybody — the page is where you sign in and, if you need to, subscribe.
craft serve --demo walks all of it and creates nothing.
One-shot reports
Not everything needs a dashboard. These print and exit.
Two flags are global: --property <id> queries a property other than the saved
default, and --theme <name> renders with a palette other than the saved one.
Piping the numbers somewhere
overview takes --format, so the same report a person reads as panels can
also leave the terminal as data.
json answers in the same shape as the site_status MCP tool: labelled
metrics with their unit, the previous period, the percentage change, the daily
user series, and the achievements that fired. The window is reported as the
first and last day the API actually returned rather than computed here — GA
resolves last 7 days in the property's timezone, which is not necessarily
this machine's.
slack wraps the same numbers as blocks. Both print the payload and nothing
else, so a weekly digest is one cron line:
Neither format needs a subscription — they render a report craft overview
already prints for free.
Claude Desktop
Restart Claude Desktop and ask it how the site is doing. The block it merges in leaves any other servers alone:
Needs craft login first and an active subscription — without either the
server still starts and its tools say which one is missing, so the client never
reports it as disconnected. craft mcp --demo runs on synthetic data without
either. More in Ask an assistant.
Audit
Every other command answers "what happened". craft audit answers the question
before it — is this property measuring the site at all, and is what it measured
worth trusting.
It reads two APIs, because measurement and configuration fail separately. The
Data API says how often purchase fired; the Admin API says whether anybody
ever told GA4 that purchase was the point. A property can pass the first and
fail the second for a year without anybody noticing, and that combination —
traffic arriving, nothing marked as an outcome — is the most common thing this
finds.
What it checks. Five things that make a number wrong:
- nothing recorded at all, which is a tag that is not installed or a property that is not the one the site reports to
- no web data stream, so there is no measurement id to put on a site
- nothing marked as a key event, or a key event configured and never fired —
GA4 matches names exactly, so
Purchaseandpurchaseare two events and only one of them counts purchasearriving without itsvalue, which makes every revenue, ARPU and ROAS figure on the property zero — including in any Google Ads account importing conversions from it- enhanced measurement switched off at the master switch, so the stream's automatic events are configured, shown as on, and collected by nothing
Five that distort one:
- page views counted twice, which is what a gtag snippet left in the page beside a GTM tag that also sends one looks like from here: bounce rate near nothing, views per session doubled
- the site referring itself, which is a visit cut in half by a domain the cross-domain configuration does not cover
- a payment or sign-in page credited with conversions, because the return trip starts a new session referred by the gateway
- an event that stopped firing between this window and the one before it, which is a tag removed, renamed, or moved behind something that no longer runs
- outcomes arriving unmarked —
sign_upfiring a thousand times with nothing in GA4 saying it is the point, so no conversion report counts it - measurement that is on and silent: the stream is configured to collect scrolls, site search, video or downloads and has recorded none of them for a month, which is the one check with no threshold to tune, because the expectation is Google's rather than ours
And five that are worth knowing before reading anything else: two names for one event, sessions GA4 could not attribute at all, a direct share high enough to suggest campaigns going out untagged, more than one site reporting into the property, and measurement the stream could be collecting and is not.
What --fix does. Most of what the audit finds is on the site, and no API
can repair it — an event that is not being sent cannot be made to arrive by
changing a setting. Two kinds of finding are the exception, and craft audit --fix applies them: marking outcomes the property is already recording as
key events, and turning on measurement the tag on the site already supports —
scrolls, outbound clicks, video, downloads. Site search and form interactions
are reported and never written: those record what a visitor typed, which is a
decision about a privacy policy rather than about whether the analytics are set
up right. Both kinds of fix are printed under the finding that motivates them
before the flag is passed, both are additive, and both are undone from the GA4
console in a click.
Nothing in the fix path can turn collection off, lower retention, or change
what the site sends. It needs Editor on the property; Viewer is enough to run
the audit and not enough to fix it.
What it will not do. It reports a symptom and names the usual cause, never the other way round — "bounce rate is 1.2%" is something the API said, and "you have two page_view tags" is a guess. It cannot see inside a GTM container, so it finds the tagging bugs that show up in the data and not the ones that only show up in the container. And every check has a floor under it: a property with eighty sessions has no meaningful bounce rate and no meaningful direct share, so those checks report as not run rather than firing on noise.
Exit codes. 0 when the property is clean, 2 when it is not, 1 on an
error — and with --fix, a finding that was just repaired does not hold the
exit code open. The same convention craft watch uses, so a weekly audit into Slack is
one cron line:
Unlike craft watch, a clean pass still prints: an audit is something somebody
asked for, and "sixteen checks, nothing found" is the answer they asked for. The
line under every report says how many checks ran, because "no findings" means
nothing without the number of ways it looked — and a check that could not run,
because the Admin API was unreadable or the property was too quiet to judge, is
reported as not run rather than as a pass.
craft audit is part of the Anacrafter Pro plan;
craft audit --demo is not, and shows the whole shape of a report before
anything is connected.
Alerts
craft watch compares the most recent complete day against the mean of the
days before it and reports what moved further than it usually does. There is
nothing to configure for it to be useful: a site's own history is the
threshold.
Three things fire. A drop or a spike past the metric's threshold, and silence — a count that went to nothing against a baseline that was not nothing, which is what a removed tag or a site that is down looks like from here. A window with no rows anywhere is reported once, as itself, rather than as six metrics all going silent.
The defaults are per-metric, because conversions swing by a third on an ordinary Tuesday and bounce rate does not: 30% for users, sessions and views, 40% for conversions, 25% for average session, 20% for bounce rate. A baseline under 10 does not fire a count at all — on a site averaging four conversions a day, one quiet day is a 25% "drop" that means nothing.
Any of it can be tuned per property:
Keys are users, sessions, views, conversions, bounce_rate,
avg_session, or the GA4 API name if you prefer it. --baseline <days>
overrides the window for one run.
What lands in Slack. Each alert carries the metric, the day's value, how far it moved, and the baseline it moved away from — plus a sparkline of the whole window ending on the day being reported, because "38% below normal" does not say whether the number slid all week or fell off a cliff last night. Where one channel carries most of a move, it is named: mostly Organic Search — 96 against 331 (79% of the move). Counts only, and only when that channel accounts for at least 35% of the total movement — under that the move was site-wide, and naming its largest slice would read as a cause. The message carries a link back to the property in GA4, and a red or amber bar down its side so an alert is told from everything else in the channel before a word of it is read.
The same day's alert is only sent once. State lives in ~/.anacraft/watch.json
and is keyed by the day being reported on, so --every 3600 sends one message
about a drop rather than twenty-four, and a new day is news again. It is
recorded only after delivery succeeds — a webhook that was unreachable has
told nobody anything, so the next pass tries again.
Exit codes. 0 when nothing fired, 2 when something did, 1 on an
error. So a shell can decide for itself:
--format slack prints nothing at all on a quiet day, which is what keeps a
cron line from posting an empty message every hour. In a loop, --webhook
does the POST itself — a daemon has nothing to pipe into.
--format chooses what the webhook receives, so a URL pointed at something
other than Slack gets a shape it can read: --format json --webhook <url>
posts the JSON object. Two exceptions. Panels have no wire form, so leaving
--format alone and passing a webhook posts the Slack blocks. And a
hooks.slack.com URL always gets blocks whatever --format says, because
Slack answers a bare JSON object with 400 no_text — the destination wins
over the flag there, which is what keeps craft slack --install from turning
--format json into an error.
Installing into Slack
Making a webhook by hand is six steps in a developer console. craft slack
does it the way craft login does Google:
Slack's own install screen carries the workspace and channel pickers, and the
incoming-webhook scope returns the URL in the OAuth response — so nothing is
copied by hand. craft watch then needs no --webhook at all.
One scope, and the narrowest one that works: permission to post to the single
channel you pick. Not chat:write, which would be permission to post anywhere
in the workspace.
The webhook URL comes from --webhook, then ANACRAFT_WEBHOOK, then whatever
craft slack --install saved in ~/.anacraft/slack.json — and deliberately
not from config.toml. That file is meant to be safe to commit to a
dotfile repo, and a URL that can post into your Slack is not.
--webhook stays for cron, CI, and workspaces where you cannot install apps.
craft watch to the terminal is part of the Anacrafter plan; delivering it to
Slack is what Anacrafter Pro adds (the same command, a --webhook).
craft watch --demo needs neither, so what an alert looks like can be seen
before anything is paid for or wired up.
The dashboard
Seven panels, each toggleable. Turn off what you do not care about and the rest reflows to fill the terminal.
Controls
Palettes
osaka-jade (default) · solarized-dark · tokyo-night · catppuccin · github · solarized-light · catppuccin-latte
The ore vocabulary — diamond, gold, redstone, lapis — is mapped onto whichever palette is selected, so the texture pack survives a theme swap.
The command is craft. anacraft is installed alongside it as an alias, so
older scripts and anything you have in muscle memory keep working.
Ask an assistant
craft mcp serves the dashboard's numbers over the Model Context
Protocol, so Claude Desktop, Claude Code, or
any MCP client can answer "how is the site doing" without a human reading a TUI.
Claude Desktop is one command. For Claude Code it is
claude mcp add anacraft -- craft mcp; any other client takes the same command
and argument. Writing a config by hand, use an absolute path — a desktop app
is not launched from a shell and does not inherit the PATH where craft
works. which craft gives the value to paste.
Every report tool takes an optional property and falls back to the saved
default, so an assistant that knows nothing about your config still gets
answers. Each also carries its own days default rather than sharing one,
because the window a question needs is part of the question — seven days is the
right answer to "how are we doing" and the wrong one to "is anything broken",
so audit_site advertises twenty-eight. configure_site, the one writer, takes a domain instead — the point
is to create the property. Responses are structured JSON — labelled numbers
carrying the property id and the date window they cover, not rendered panels.
One writer. configure_site creates a property and web stream for a domain
the account doesn't track yet and returns the tag; it works off the stored
grant rather than opening a browser. Nothing else here starts an OAuth flow,
writes to ~/.anacraft/, or changes the default property: login and use
stay human-only commands, and configure_site never sets the default either
(say craft use for that). If no
credentials are stored the tools say to run craft login rather than opening a
browser inside your client's subprocess. Identical reports
are cached for a minute so a chatty agent does not burn the GA4 quota that the
dashboard needs.
Subscription. craft mcp is the Anacrafter Elite plan — craft subscribe
for the $2.99 starter, --plan pro / --plan elite for the two above it, and
anacraft.dev/pricing for what is on each
side of that line. It opens Stripe,
waits for the payment to clear, and writes supporter = true (and the plan)
itself; the
dashboard, craft watch and the MCP server re-check on launch and keep that
line current. The
record is keyed to the Google account you signed in with, so a second machine
only has to craft login — add --check to look it up without opening a
browser. Missing it does not take the process
down: an MCP client reads an early exit as "server disconnected", which says
nothing about what to fix, so the server starts, the handshake succeeds, and
every tool call answers with the sentence that gets you unstuck. The same goes
for a missing login. craft mcp --demo is ungated, so the server can be wired
up and looked at first.
Configuration
Config honours $XDG_CONFIG_HOME. Tokens stay out of ~/.config on purpose —
that directory ends up in dotfile repos, and a refresh token has no business
travelling with it. A pre-0.4 ~/.anacraft/config.json is migrated on first run.
Multiple properties
craft use <id> adds a property rather than replacing the last one, so the
config accumulates. In the dashboard, tab cycles between them, and whichever
one you quit on becomes active — so the dashboard and the rest of the CLI do
not disagree about which property is the current one. Passing through on the
way somewhere else costs nothing; landing is what commits it.
active is what every command reads when you do not say otherwise. The order
is --property <id>, then ANACRAFT_PROPERTY_ID, then active, so a flag or
an exported id will quietly outrank craft use for as long as it is set.
Every key under [[property]] is optional and falls back to the global default,
so switching to a property that saved nothing lands on the defaults rather than
inheriting the previous property's window. Command-line flags beat both.
ANACRAFT_PROPERTY_ID overrides the saved property if you would rather not keep
one on disk.
Your own OAuth client
Official builds carry one, so craft login works with no setup. To use your own
instead, set ANACRAFT_OAUTH_CLIENT_ID and ANACRAFT_OAUTH_CLIENT_SECRET, or
write ~/.anacraft/client.json. Both take precedence over the built-in client,
and registering your own Google Cloud project also insulates you from other
people's quota consumption.
Setting up GA4
app.anacraft.dev is the preferred route: sign in,
Create a new property, and the property, data stream and tag are done
without the console. craft configure <domain> does the same from a terminal.
Both are part of a subscription — the dashboard on Elite, the command on
Anacrafter — and nothing is created in the Analytics account until the payment
clears. The rest of the Google side — access management, retention,
key events, API enablement — is console work, and is documented in
Configure your analytics.
craft delete <domain|id> is the way back out, and on its own it does less
than it sounds like: it forgets the property here so the dashboard stops
opening on it, then prints the console link and the two clicks that delete it.
Nothing in Analytics changes.
craft delete <domain|id> --all does those two clicks for you. It is the only
command that deletes anything in Google, it only ever touches the property you
named, and it has to be typed — a bare craft delete will never do it. What it
reaches for is Google's own soft delete, so the property lands in your
Analytics account's trash and stays restorable from the console for 35 days
before it and its data are gone for good.
Cloned the repo and use Claude Code?
.claude/skills/anacraft/ ships as a skill — installing, connecting a
property, driving the dashboard, wiring up craft mcp, and what each error
message actually means. Ask Claude to set anacraft up, or paste a failing
command at it.
Requirements
- A Google Analytics 4 property
- A terminal with truecolor support
- Rust 1.74+, if you are building from source
Contributing
cargo run -- dash --demo gets you a working dashboard with no Google account
attached. See CONTRIBUTING.md for the layout of the code and
what CI expects.
License
来源:README.md,提交 4931825
工具
0版本历史
1- v0.42.0最新Sep 30, 2026
