Start free
    Menu
    How it worksIntegrationsCustomersPricingSign in

    integrations tools umami

    Umami MCP for your AI agent

    Cogny's Umami integration exposes 18 tools (13 read, 4 write, 1 destructive) to an AI agent over MCP. The same tools are available on every plan, from your own AI client or inside the Cogny app.

    • 13readonly reads data.
    • 4writecreates or changes something.
    • 1destructivedeletes, removes or replaces something.

    Over MCP your own AI client asks before it runs a write. To take a tool away from your agent, block it in Settings → Integrations. Plans, approvals and limits

    set it up.

    Add Cogny to your AI client once, then connect Umami in Cogny. Every Umami tool below appears in the client.

    • Claude CodeRun claude mcp add --transport http cogny https://app.cogny.com/mcp, then authorise in the browser.
    • Claude.aiSettings → Connectors → Add custom connector, URL https://app.cogny.com/mcp, then log in and pick your workspace.
    • ChatGPTSettings → Apps → Advanced settings → Developer mode → Create app, URL https://app.cogny.com/mcp, authentication OAuth.
    • CursorIn Cogny, Settings → Data & Integrations → Connect AI Clients shows the block to paste into .mcp.json, with an API key.
    • CodexRun codex mcp add cogny --url https://app.cogny.com/mcp.

    Full setup, and how to undo it

    Notes

    Umami connects with two values: your Umami address and an API key from Umami → Settings → API keys. For Umami Cloud the address is https://cloud.umami.is; for a self-hosted Umami it is the address you open Umami at. The key has the permissions of the Umami user it belongs to, including their teams, so Cogny sees the websites that user sees.

    Every report takes a website_id from list_websites, a date range (start_date and end_date, YYYY-MM-DD, both inclusive) and a timezone (UTC by default). Without dates a report covers the last 7 days. Any report can be narrowed with filters such as page path, referrer, country, device, browser, UTM values or custom event name.

    In breakdown, visitor dimensions (referrer, channel, country, device, browser, UTM values) count unique visitors and page dimensions (path, title, event) count views or events. The response says which.

    Umami Cloud allows 50 API calls every 15 seconds per key.

    create_annotation, update_annotation, delete_annotation, create_goal and update_goal change things in Umami and need edit rights on the website. They stay ask-first until you allow them in Settings.

    Known gaps

    • A self-hosted Umami needs version 3.4 or later: older versions have no API keys, and annotations and saved goals arrive with 3.4. Username and password sign-in isn't supported.
    • A self-hosted Umami has to be reachable from the internet over https.
    • No tools for sessions, the visitor journey, funnels, retention, attribution, revenue, heatmaps, session replays or custom event properties.
    • Saved goals can be created and edited but not deleted, and funnels and segments can't be created.
    • Websites, teams, users and share links can't be added or changed.
    • get_goal_conversions returns one total for the range, not a series per day.

    what each tool does.

    Read 13 · only reads data

    • list_websitesReadList the websites tracked in Umami, with the id every report takes.
    • get_websiteReadGet one Umami website: its name, domain and team.
    • aggregateReadGet a website's traffic totals for a period: pageviews, visitors, visits, bounce rate and visit duration, with the previous period to compare.
    • timeseriesReadGet a website's pageviews and visits over time, per minute, hour, day, month or year.
    • breakdownReadRank a website's traffic by one dimension: top pages, referrers, channels, countries, devices, browsers, UTM campaigns or custom events.
    • get_event_statsReadGet custom event totals for a period: events fired, distinct events, and the visitors and visits that fired them, with the previous period.
    • event_timeseriesReadGet custom event counts over time, one series per event name.
    • list_eventsReadList the latest pageviews and custom events on a website, newest first: page, event name, referrer and time.
    • realtime_visitorsReadGet how many visitors are on a website right now (active in the last 5 minutes).
    • get_realtimeReadGet the last 30 minutes on a website: totals, top pages, referrers and countries, and the newest events.
    • list_annotationsReadList a website's annotations: the dated notes (launches, campaigns, tracking changes) shown on Umami's charts.
    • list_goalsReadList a website's saved goals in Umami: each one a page path or custom event that counts as a conversion.
    • get_goal_conversionsReadGet how many visitors converted on a goal in a period, out of all visitors, and the conversion rate.

    Write 4 · creates or changes something

    • create_annotationWriteAdd an annotation to a website's charts in Umami, such as a launch, a campaign start or a tracking change.
    • update_annotationWriteChange an annotation's date, text or all-day setting in Umami.
    • create_goalWriteSave a goal on a website in Umami: a page path or custom event that counts as a conversion.
    • update_goalWriteChange a saved goal's name, description, or the page or event it counts, in Umami.

    Destructive 1 · deletes, removes or replaces something

    • delete_annotationDestructiveDelete an annotation from a website in Umami; it can't be restored.

    Exact input schemas come from tools/list once Umami is connected; the free plan is enough to check. Missing something? Your agent can ask for it with request_feature.

    This page as markdownAll integrations