Amami MCP docs

API reference

Use the API when you need programmatic access from a backend, scheduled job, internal dashboard, or data pipeline. Use MCP when an AI assistant should choose tools and explain analytics in natural language.

Base URLs

Cloud dashboard:

https://dashboard.amami.dev

Cloud API:

https://api.amami.dev

Self-hosted compatible instance:

https://analytics.example.com/api

Authentication

Use API keys for automation:

Authorization: Bearer YOUR_API_KEY

or the header supported by your Amami-compatible deployment:

x-umami-api-key: YOUR_API_KEY

Keep keys in server-side environment variables or a secret store. Do not expose them in browser code or paste them into AI chat.

Common resources

Website management:

  • List websites.
  • Create a website when write access is enabled.
  • Read website settings.
  • Update website metadata when allowed.

Analytics:

  • Stats for a date range.
  • Pageview time series.
  • Metrics by URL, referrer, country, browser, operating system, or device.
  • Realtime active visitors.
  • Events and sessions when available.
  • Reports when enabled by the deployment.

Teams and users:

  • Team-scoped website access.
  • Current user profile.
  • API key ownership and permissions.

AI and MCP:

  • The MCP server wraps API access into assistant-callable tools.
  • AI workflows should use MCP unless you are building your own integration.

Time ranges

Many analytics endpoints use start and end timestamps. Keep these rules:

  • Use explicit time zones when presenting results.
  • Compare equal-length periods.
  • Avoid mixing today with complete past days unless the report says so.
  • For launch analysis, use minute or hour granularity.
  • For SEO and content review, use 7, 14, 30, or 90 day windows.

Error handling

Plan for:

  • 401: missing or invalid authentication.
  • 403: the key does not have access to the requested website or team.
  • 404: website, report, or resource not found.
  • 429: rate limit.
  • 5xx: service or deployment issue.

When an AI assistant receives one of these errors, it should explain the likely cause and the least-privilege fix rather than asking for passwords.

When to use MCP instead

Use MCP when you want:

  • Browser-based login and authorization.
  • A local config that avoids placing secrets in chat.
  • Natural language analysis.
  • Agent-guided website setup.
  • AI recommendations with evidence from analytics.