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 analytics.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://analytics.amami.dev unless AMAMI_API_URL is also set. | | AMAMI_API_URL | hosted or self-hosted | Instance base URL, e.g. https://stats.example.com (/api appended). Known Amami hosted URLs are treated as cloud. | | 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://analytics.amami.dev/api. Custom instances that issue API keys can use AMAMI_API_URL + AMAMI_API_KEY instead.

Upgrading to 0.1.5

Version 0.1.5 fixes 401 Unauthorized responses caused by the legacy dashboard.amami.dev URL redirecting API requests across origins and dropping the Bearer header. Existing AMAMI_API_URL, AMAMI_API_BASE_URL, AMAMI_APP_URL, tracking-script, and short-link settings that point to the known legacy hosted domain are normalized directly to analytics.amami.dev. API keys do not need to be replaced. Custom and self-hosted domains remain unchanged.

Surrounding quotes are stripped from values defensively. Setup-generated credentials in ~/.amami-analytics-mcp/.env are loaded automatically. For another file, use --amami-env-file (rather than Node's reserved --env-file flag):

npx amami-analytics-mcp --amami-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 (analytics.amami.dev)

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

Use API-key mode:

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp"],
      "env": {
        "AMAMI_API_URL": "https://analytics.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://analytics.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

The Vercel and single-tenant HTTP modes use MCP_AUTH_TOKEN; without it they reject every request (fail closed). Use the OAuth HTTP mode below for a public multi-user endpoint: each caller signs in to Amami and receives an independently revocable, read-only token.

Deploy to Vercel

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

1. Push this repo to GitHub and Import it in Vercel.
2. 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.
3. Deploy. Your endpoint is https://<deployment>.vercel.app/api/mcp.
4. 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.

Public OAuth endpoint (Railway / Docker)

For a public Smithery-style endpoint, deploy the standalone HTTP server with a dedicated HTTPS domain. In OAuth-only mode, do not configure a shared AMAMI_API_KEY or MCP_AUTH_TOKEN: the server validates each caller's Amami OAuth token and forces the read-only tool tier.

docker run --rm -p 8787:8787 \
  -e MCP_OAUTH_RESOURCE_URL=https://mcp.amami.dev/mcp \
  -e MCP_OAUTH_AUTHORIZATION_SERVER=https://analytics.amami.dev \
  -e AMAMI_API_URL=https://analytics.amami.dev \
  -e MCP_ALLOWED_HOSTS=mcp.amami.dev \
  amami-mcp

The service exposes /.well-known/oauth-protected-resource/mcp and challenges unauthenticated calls with 401 plus OAuth resource metadata. The Amami dashboard must be deployed with its /oauth/authorize, /oauth/token, and /.well-known/oauth-authorization-server routes before this mode is enabled.

One process, two compatible domains

One amami-mcp-http process can keep an existing shared-token resource while serving a new OAuth resource. Bind both domains to that same service, then configure the resource URLs explicitly:

MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
MCP_LEGACY_RESOURCE_URL=https://analytics.amami.dev/mcp
MCP_OAUTH_RESOURCE_URL=https://mcp.amami.dev/mcp
MCP_OAUTH_AUTHORIZATION_SERVER=https://analytics.amami.dev
AMAMI_API_URL=https://analytics.amami.dev
AMAMI_API_KEY=service_key_for_legacy_resource_only
MCP_ALLOWED_HOSTS=analytics.amami.dev,mcp.amami.dev

analytics.amami.dev/mcp accepts only MCP_AUTH_TOKEN; mcp.amami.dev/mcp accepts only a per-user OAuth token and is read-only. The process returns 404 for other hosts, so a shared token cannot be used to bypass OAuth on the new domain. Existing local clients that call https://analytics.amami.dev/api do not use this HTTP gateway and remain unchanged.

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 — single-tenant deployments use constant-time MCP_AUTH_TOKEN comparison; public deployments use OAuth discovery and validate each caller's Amami key before an MCP request is served.
• 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

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

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

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