amami-analytics-mcp

amami-analytics-mcp

Security-first Model Context Protocol server for Amami analytics. Set up, analyze, report on, and (when you allow it) administer your analytics instance from any MCP client.

• 🚀 Local-first — npx amami-analytics-mcp, zero build step, ~2 runtime deps.
• ☁️ Or host it — deploy to Vercel (one Web function) or run the bundled Docker HTTP server. One shared core, three transports.
• 🔒 Credential-safe — secrets live in env only; never placed in tool arguments, outputs, or logs (two-layer redaction). Remote endpoints are bearer-gated and fail closed.
• 🎚️ Least privilege — read-only by default; write and admin tiers are opt-in; destructive ops (delete/reset) are double-gated.
• 📊 Comprehensive — full Amami analytics API surface: stats, metrics, events, sessions, reports (funnel, retention, journey, attribution, revenue, UTM, web-vitals), segments, teams, share links, event ingestion, and self-hosted user administration.

Contents

• Quickstart (local / npx)
• Configuration
• Capability tiers
• MCP client setup
• Remote hosting · Vercel · Docker / self-host
• Security model
• Tool reference
• Prompts & resources
• Development
• 中文调试命令汇总

Quickstart (local / npx)

No install required. Point your MCP client at:

npx -y amami-analytics-mcp

…with credentials supplied via environment variables. For the default Amami dashboard, create an API key in the dashboard and set AMAMI_API_KEY. For another Amami-compatible instance, set AMAMI_API_URL + AMAMI_USERNAME + AMAMI_PASSWORD. See MCP client setup for copy-paste configs.

By default the server is read-only (32 analytics tools). Opt into writes/admin explicitly — see Capability tiers.

Browser login setup

If you do not already have an API key, run the one-time browser setup flow:

npx -y amami-analytics-mcp setup --write

The command opens dashboard.amami.dev, lets you log in or create an account, creates an API key for MCP, and stores it in ~/.amami-analytics-mcp/.env with file mode 0600. The MCP server auto-loads that default file, so configure your MCP client to launch:

npx -y amami-analytics-mcp

The browser step is intentionally interactive: the user must log in/register on Amami and click Authorize MCP. Agents should not collect passwords or complete this flow through background API calls.

Use setup --app-url https://your-amami.example.com --write for a self-hosted Amami instance that supports the MCP authorization endpoints.

Configuration

All configuration is via environment variables (secrets) and optional CLI flags (non-secrets).

Variable	Mode	Description
AMAMI_API_KEY	Amami/default	API key for https://dashboard.amami.dev unless AMAMI_API_URL is also set.
AMAMI_API_URL	custom/self-hosted	Instance base URL, e.g. https://stats.example.com (/api appended).
AMAMI_USERNAME / AMAMI_PASSWORD	self-hosted	Login credentials → bearer token (cached, auto-renewed on 401).
AMAMI_TEAM_ID	both	Scope website listings to a team (optional).
AMAMI_DEFAULT_TIMEZONE	both	IANA tz for time-series tools (default UTC).
AMAMI_ENABLE_WRITE	both	1 to expose create/update + send_event tools.
AMAMI_ENABLE_ADMIN	both	1 to expose user-management tools (self-hosted only).
AMAMI_ALLOW_DESTRUCTIVE	both	1 — also required to expose delete/reset tools.
MCP_AUTH_TOKEN	remote	Shared-secret bearer required by the Vercel/HTTP endpoints.

By default, AMAMI_API_KEY connects to https://dashboard.amami.dev/api. Custom instances that issue API keys can use AMAMI_API_URL + AMAMI_API_KEY instead.

Surrounding quotes are stripped from values defensively. Setup-generated credentials in ~/.amami-analytics-mcp/.env are loaded automatically. For another file, use --env-file:

npx amami-analytics-mcp --env-file .env.local

Run npx amami-analytics-mcp --help for the full flag list.

Capability tiers

The server exposes only the tools for the tiers you enable, layered on top of the Amami API's own role-based access (the API still enforces your account's real permissions — tiers just decide which tools are even visible).

Tier	Enable with	Adds	Example tools
read	(always on)	analytics, reporting & tracking code	get_tracking_script, get_stats, get_metrics, report_funnel
write	AMAMI_ENABLE_WRITE=1	mutations + ingestion	create_website, create_short_link, send_event, add_team_member
admin	AMAMI_ENABLE_ADMIN=1 (self-hosted)	user administration	create_user, set_user_role
destructive	AMAMI_ALLOW_DESTRUCTIVE=1 (+ write/admin)	delete / reset	delete_website, reset_website, delete_user

Tool counts: 36 read → 49 with write → 56 with destructive → 62 at full tier on self-hosted. Admin tools are disabled for the default hosted Amami API, and the server explains why at startup. Destructive tools carry MCP destructiveHint annotations so clients can warn before running them.

MCP client setup

Amami dashboard (dashboard.amami.dev)

https://dashboard.amami.dev is the default API target. If you only provide AMAMI_API_KEY, the MCP server connects to https://dashboard.amami.dev/api.

Use API-key mode:

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": {
        "AMAMI_API_URL": "https://dashboard.amami.dev",
        "AMAMI_API_KEY": "your_amami_api_key",
        "AMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

If needed, use username/password login explicitly:

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": {
        "AMAMI_API_URL": "https://dashboard.amami.dev",
        "AMAMI_USERNAME": "your_amami_email_or_username",
        "AMAMI_PASSWORD": "your_amami_password",
        "AMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

Or omit AMAMI_API_URL and rely on the default Amami dashboard target:

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": {
        "AMAMI_API_KEY": "your_amami_api_key",
        "AMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

To connect to a different Amami-compatible instance, set AMAMI_API_URL.

Claude Desktop / Cursor (claude_desktop_config.json / .cursor/mcp.json)

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": {
        "AMAMI_API_KEY": "your_amami_api_key"
        // custom/self-hosted instead:
        // "AMAMI_API_URL": "https://stats.example.com",
        // "AMAMI_USERNAME": "admin",
        // "AMAMI_PASSWORD": "••••••",
        // opt into writes:
        // "AMAMI_ENABLE_WRITE": "1"
      }
    }
  }
}

Claude Code

claude mcp add amami \
  -e AMAMI_API_KEY=your_amami_api_key \
  -- npx -y amami-analytics-mcp

VS Code (.vscode/mcp.json)

{
  "servers": {
    "amami": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": { "AMAMI_API_KEY": "your_amami_api_key" }
    }
  }
}

Remote hosting

Both remote transports require MCP_AUTH_TOKEN; without it they reject every request (fail closed). Clients authenticate with Authorization: Bearer <MCP_AUTH_TOKEN>.

Deploy to Vercel

The repo ships a single Web function at api/mcp.ts (no Next.js required).

• Push this repo to GitHub and Import it in Vercel.
• Set Environment Variables: your Amami credentials (AMAMI_API_KEY or AMAMI_API_URL+AMAMI_USERNAME+AMAMI_PASSWORD), optional tier flags, and a strong MCP_AUTH_TOKEN.
• Deploy. Your endpoint is https://<deployment>.vercel.app/api/mcp.
• Harden: enable Vercel Deployment Protection (locks preview URLs) and Firewall.

Connect a Streamable-HTTP-capable client to the URL with the bearer header. stdio-only clients bridge via:

npx mcp-remote https://<deployment>.vercel.app/api/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Docker / self-host

Runs the framework-free standalone HTTP server (amami-mcp-http):

docker build -t amami-mcp .
docker run --rm -p 8787:8787 \
  -e AMAMI_API_KEY=your_amami_api_key \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  amami-mcp
# → endpoint at http://localhost:8787/mcp  (health: /health)

Or without Docker: MCP_AUTH_TOKEN=… AMAMI_API_KEY=… npx -y amami-analytics-mcp amami-mcp-http (bin amami-mcp-http). Set HOST, PORT, optional MCP_ALLOWED_HOSTS (enables DNS-rebinding protection), or MCP_ALLOW_INSECURE=1 for localhost-only unauthenticated dev.

Security model

• Secrets in env only. Never committed, never passed as flags, never persisted. The self-hosted bearer token is cached in memory and re-fetched on 401.
• Never logged or echoed. A redaction layer scrubs secrets by key and by literal value from every log line, error, and tool result. get_me and user/admin responses are sanitized of token/authKey/shareToken. stdio diagnostics go to stderr only (stdout is the JSON-RPC channel).
• Remote endpoints are auth-gated and fail closed — constant-time bearer comparison; no MCP_AUTH_TOKEN ⇒ all requests rejected.
• Least privilege by default — read-only unless you opt in; destructive operations double-gated and annotated.
• No third-party credential collection. Run your own instance of this server. Never point credentials at someone else's hosted MCP endpoint.

See SECURITY.md for the full threat model and disclosure policy.

Tool reference

Read tier (32 — always on)

list_websites · get_website · get_website_daterange · get_tracking_script · get_active_visitors · get_realtime · get_stats · get_pageviews · get_metrics · get_website_values · get_events · get_event_data · list_sessions · get_session · get_session_activity · get_session_stats · get_session_properties · report_funnel · report_retention · report_journey · report_goals · report_attribution · report_revenue · report_utm · report_breakdown · list_reports · get_report · list_segments · get_segment · list_teams · get_team · get_team_members · get_me

Write tier (AMAMI_ENABLE_WRITE)

create_website · update_website · manage_website_share · transfer_website · create_short_link · update_short_link · send_event · create_team · update_team · join_team · add_team_member · update_team_member · create_segment · update_segment · create_report · update_report

Destructive (also needs AMAMI_ALLOW_DESTRUCTIVE): delete_website · reset_website · delete_short_link · delete_team · remove_team_member · delete_segment · delete_report

Admin tier (AMAMI_ENABLE_ADMIN — self-hosted)

list_users · get_user · create_user · update_user · set_user_role

Destructive: delete_user

Every tool returns a concise text summary plus a typed structuredContent payload, and accepts flexible date ranges (range: "7d" | "today" | "this-month", or explicit startAt/endAt).

Prompts & resources

Prompts (server-side, teach correct tool-chaining): analytics_report, traffic_overview, top_pages, acquisition_channels, realtime_check, funnel_analysis, retention_analysis, audience_insights, compare_periods.

Resources: amami://websites, amami://website/{id}, amami://me (sanitized).

Development

npm install
npm run build        # tsup → dist/{cli,http,server}.js
npm test             # vitest (58 tests)
npm run typecheck    # tsc --noEmit
npm run inspect      # MCP Inspector against the stdio CLI

Architecture: a single registerAll(server, ctx) core (src/server.ts) is shared by the stdio CLI (src/bin/cli.ts), the standalone HTTP server (src/http/server.ts), and the Vercel function (api/mcp.ts) — so the tool surface never drifts between local and hosted modes. See the design spec.

Publishing

The repo includes a manual GitHub Actions workflow: Actions → Publish npm → Run workflow.

Before running it, add a repository secret named NPM_TOKEN with permission to publish amami-analytics-mcp. The workflow runs install, tests, typecheck, build, then npm publish.

License

MIT © Mateusz Siatrak