Amami MCP docs

Security model

Amami is designed so AI assistants can analyze your website data without taking over sensitive account actions. The assistant can guide setup, call MCP tools, and summarize analytics. You still control login, registration, authorization, and credential storage.

The recommended setup flow is:

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

The CLI opens Amami in your browser. You log in or register yourself, then click Authorize MCP. The CLI receives a local callback and creates an API key for MCP access.

Agents should not ask for your password, complete account registration in the background, or bypass the authorization screen.

Credentials stay local

Setup-generated credentials are stored in:

~/.amami-analytics-mcp/.env

The file is created with restrictive permissions. The MCP server auto-loads it, so most client configs only need:

{
  "mcpServers": {
    "amami": {
      "command": "npx",
      "args": ["-y", "amami-analytics-mcp@latest"]
    }
  }
}

Manual API keys should stay in MCP client environment variables or a secret store, not in chat.

Least privilege by default

Amami MCP exposes tools by capability tier:

  • Read tools are always available for analytics and reporting.
  • Write tools require AMAMI_ENABLE_WRITE=1 or browser setup with --write.
  • Admin tools require explicit admin enablement and are intended for self-hosted use.
  • Destructive tools require an additional explicit flag.

This means an assistant can inspect traffic safely by default. Creating websites, sending events, or changing resources requires the write tier.

What AI can access

After authorization, your assistant can use Amami tools to:

  • List websites available to the authorized account.
  • Read stats, pageviews, metrics, reports, sessions, events, referrers, devices, countries, UTM campaigns, and live visitors.
  • Create a tracked website when write access is enabled.
  • Send test or server-side events when write access is enabled.
  • Explain traffic movement and suggest growth improvements based on your data.

The assistant should base recommendations on tool results, not generic advice.

Agents may guide you through setup, but sensitive account actions stay under your control:

  • You type login or registration details in the browser.
  • You approve MCP authorization in the browser.
  • You decide whether write tools are enabled.
  • You decide whether a self-hosted instance can expose admin tools.
  • You decide whether a shared report is safe to send externally.

If a setup path asks for a password or API key in chat, use browser setup or a local secret store instead.

Design constraints

  • Login, registration, and authorization happen in the browser.
  • Secrets live in environment variables or the setup-generated local env file.
  • The server avoids placing credentials in command arguments.
  • Remote endpoints require bearer authentication and fail closed when the token is missing.
  • Destructive behavior is double-gated.
  • Product dashboards remain available; MCP adds an AI-native control and analysis layer.

For team access patterns, read Teams and sharing. For migration cleanup, read Migration guide.