Fathom Analytics MCP by usefulapi

The connected API token's name, permissions (abilities: "*" = Admin, "all-sites-readonly", or per-site read:<id> / manage:<id>) and timestamps. The secret value is never returned. Good first call to know which tools will work. GET /token.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The Fathom account that owns the API token: id, name and email. Needs an Admin token (the * scope). GET /account.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the sites the token can read (id, name, sharing, timezone, created_at), oldest first. The site id is what every report tool takes. Needs an Admin or all-sites read-only token; a token scoped to a single site cannot list sites, so use fathom_get_site with that site id instead. Paged: pass next.starting_after. GET /sites.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Items per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "starting_after": {
      "description": "Page forward: pass next.starting_after from the previous reply (an object id).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    },
    "ending_before": {
      "description": "Page backward from this object id (newest first). Not together with starting_after.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One site: id, name, sharing (none/private/public), timezone and created_at. GET /sites/{site_id}.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    }
  },
  "required": [
    "site_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List a site's events (conversions/goals): every event name the site has tracked plus events with a currency set, sorted by name. Identify events by name (use it as event_name in fathom_get_aggregation); the id is only a paging cursor. Paged: pass next.starting_after. GET /sites/{site_id}/events.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "limit": {
      "description": "Items per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "starting_after": {
      "description": "Page forward: pass next.starting_after from the previous reply (an object id).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    },
    "ending_before": {
      "description": "Page backward from this object id (newest first). Not together with starting_after.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    }
  },
  "required": [
    "site_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List a site's milestones (dated annotations on reports, such as a redesign launch or a campaign start), oldest first. Paged: pass next.starting_after. GET /sites/{site_id}/milestones.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "limit": {
      "description": "Items per page, 1-100 (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "starting_after": {
      "description": "Page forward: pass next.starting_after from the previous reply (an object id).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    },
    "ending_before": {
      "description": "Page backward from this object id (newest first). Not together with starting_after.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$"
    }
  },
  "required": [
    "site_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One milestone: id, name, milestone_date, created_at, updated_at. GET /sites/{site_id}/milestones/{milestone_id}.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "milestone_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "The milestone id (a UUID, from fathom_list_milestones)."
    }
  },
  "required": [
    "site_id",
    "milestone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fathom's custom report (the dashboard's numbers): aggregate pageviews or one event over a date range, optionally grouped by date and/or fields and filtered. Pageviews: aggregates visits (unique site visits), uniques (unique page visits), pageviews, avg_duration (seconds), bounce_rate. Events (entity event + event_name): conversions, unique_conversions, value (in cents). Examples: top pages = field_grouping [pathname], sort_by pageviews:desc; traffic sources = [referrer_source] or [referrer_hostname]; AI referrals = [ai_source]; daily trend = date_grouping day. All numbers come back as strings. Dates are in the site's timezone; hour grouping only for ranges up to 7 days. Grouped reports return at most 500 rows unless limit is set (max 1000, no paging), so narrow with filters or dates. Data before March 2021 cannot be grouped/filtered. GET /aggregations.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "entity": {
      "type": "string",
      "enum": [
        "pageview",
        "event"
      ],
      "description": "pageview = site traffic; event = one event's conversions (needs event_name)."
    },
    "event_name": {
      "description": "For entity event: the event's name, as listed by fathom_list_events.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "aggregates": {
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "visits",
          "uniques",
          "pageviews",
          "avg_duration",
          "bounce_rate",
          "conversions",
          "unique_conversions",
          "value"
        ]
      },
      "description": "Metrics. pageview: visits, uniques, pageviews, avg_duration, bounce_rate. event: conversions, unique_conversions, value."
    },
    "date_grouping": {
      "description": "Group by time (omit for one total). hour only for ranges up to 7 days.",
      "type": "string",
      "enum": [
        "hour",
        "day",
        "month",
        "year"
      ]
    },
    "field_grouping": {
      "description": "Group by these fields, e.g. [pathname] or [referrer_source, utm_campaign].",
      "minItems": 1,
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "hostname",
          "pathname",
          "entry_page",
          "exit_page",
          "referrer_hostname",
          "referrer_pathname",
          "referrer_source",
          "ai_source",
          "browser",
          "country_code",
          "city",
          "state",
          "region",
          "device_type",
          "operating_system",
          "utm_campaign",
          "utm_content",
          "utm_medium",
          "utm_source",
          "utm_term",
          "keyword",
          "ref"
        ]
      }
    },
    "sort_by": {
      "description": "\"<field>:asc|desc\" with a field from aggregates or field_grouping (or timestamp with date_grouping), e.g. pageviews:desc.",
      "type": "string",
      "maxLength": 64
    },
    "date_from": {
      "description": "Start, YYYY-MM-DD (start of day) or \"YYYY-MM-DD HH:MM:SS\", in the site's timezone. Default: the first recorded data.",
      "type": "string",
      "minLength": 10,
      "maxLength": 19
    },
    "date_to": {
      "description": "End, YYYY-MM-DD (end of day) or \"YYYY-MM-DD HH:MM:SS\", in the site's timezone. Default: now.",
      "type": "string",
      "minLength": 10,
      "maxLength": 19
    },
    "limit": {
      "description": "Row cap, 1-1000 (default 500 when grouping by fields).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "filters": {
      "description": "Filters, all applied (AND). Example: [{\"property\":\"country_code\",\"operator\":\"is\",\"value\":\"GB\"}].",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "property": {
            "type": "string",
            "enum": [
              "domain",
              "hostname",
              "pathname",
              "entry_page",
              "exit_page",
              "referrer_hostname",
              "referrer_pathname",
              "referrer_source",
              "ai_source",
              "browser",
              "country_code",
              "city",
              "state",
              "region",
              "device_type",
              "operating_system",
              "utm_campaign",
              "utm_content",
              "utm_medium",
              "utm_source",
              "utm_term",
              "ref"
            ],
            "description": "Field to filter on (domain is filter-only; keyword cannot be filtered)."
          },
          "operator": {
            "type": "string",
            "enum": [
              "is",
              "is not",
              "is like",
              "is not like",
              "matching",
              "not matching"
            ],
            "description": "is, is not, is like (contains, * wildcards), is not like, matching (regex), not matching. Categorical fields (device_type, operating_system, browser, country_code, city, state, region) allow only is / is not."
          },
          "value": {
            "type": "string",
            "maxLength": 1000,
            "description": "The value to compare with, always a string (e.g. /pricing, GB, Mobile, ChatGPT)."
          }
        },
        "required": [
          "property",
          "operator",
          "value"
        ]
      }
    }
  },
  "required": [
    "site_id",
    "entity",
    "aggregates"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Live visitors on a site right now: the total, and with detailed true the top 150 pages (hostname, pathname, total) and top 150 referrers. GET /current_visitors.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "detailed": {
      "description": "true = also the top pages and referrers (default false: only the count).",
      "type": "boolean"
    }
  },
  "required": [
    "site_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a new site in the Fathom account (returns its id, used in the tracking code). Needs an Admin token. Sharing private needs share_password; multi_domain true needs multi_domain_option. POST /sites.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Site name (up to 255 characters; need not match the URL)."
    },
    "sharing": {
      "description": "Dashboard sharing: none (default), private (password) or public.",
      "type": "string",
      "enum": [
        "none",
        "private",
        "public"
      ]
    },
    "share_password": {
      "description": "Required when sharing is private: the password for the shared dashboard.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "pattern": "^[A-Za-z][A-Za-z0-9_+-]*(\\/[A-Za-z0-9_+-]+){0,2}$",
      "description": "Reporting timezone as a TZ database name, e.g. America/New_York, Europe/London, UTC."
    },
    "multi_domain": {
      "description": "true = the site may track multiple domains.",
      "type": "boolean"
    },
    "multi_domain_option": {
      "description": "Required when multi_domain is true: report domains combined or separate.",
      "type": "string",
      "enum": [
        "combined",
        "separate"
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Change a site's name, sharing, timezone or multi-domain setting (send only what changes). Changing the timezone changes how reports are bucketed. Needs a manage token for the site. POST /sites/{site_id}.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "name": {
      "description": "New site name (up to 255 characters).",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "sharing": {
      "description": "Dashboard sharing: none, private (needs share_password) or public.",
      "type": "string",
      "enum": [
        "none",
        "private",
        "public"
      ]
    },
    "share_password": {
      "description": "Required when setting sharing to private.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "timezone": {
      "type": "string",
      "maxLength": 64,
      "pattern": "^[A-Za-z][A-Za-z0-9_+-]*(\\/[A-Za-z0-9_+-]+){0,2}$",
      "description": "Reporting timezone as a TZ database name, e.g. America/New_York, Europe/London, UTC."
    },
    "multi_domain": {
      "description": "true = the site may track multiple domains.",
      "type": "boolean"
    },
    "multi_domain_option": {
      "description": "Required when multi_domain is true: combined or separate.",
      "type": "string",
      "enum": [
        "combined",
        "separate"
      ]
    }
  },
  "required": [
    "site_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Set the currency of an event's value by event name (works before the event is first tracked). Needs a manage token for the site. POST /sites/{site_id}/events/currency.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "event_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The event's name exactly as tracked (up to 255 characters; fathom_list_events lists them)."
    },
    "currency": {
      "type": "string",
      "enum": [
        "dollar",
        "pound",
        "euro",
        "yuan",
        "peso",
        "shekel",
        "yen",
        "won",
        "hryvnia",
        "franc",
        "rupee",
        "integer",
        "none"
      ],
      "description": "dollar, pound, euro, yuan, peso, shekel, yen, won, hryvnia, franc, rupee, integer (a plain number) or none."
    }
  },
  "required": [
    "site_id",
    "event_name",
    "currency"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Remove the currency set for an event, so it uses the site's default again. The event and its completion data stay. Needs a manage token for the site. DELETE /sites/{site_id}/events?name=.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "event_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The event's name exactly as tracked (fathom_list_events lists them)."
    }
  },
  "required": [
    "site_id",
    "event_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Add a milestone (a dated annotation shown on the site's reports, e.g. a launch or campaign start). Needs a manage token for the site. POST /sites/{site_id}/milestones.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30,
      "description": "Milestone name (up to 30 characters), e.g. Redesign launch."
    },
    "milestone_date": {
      "type": "string",
      "description": "The milestone's date, YYYY-MM-DD."
    }
  },
  "required": [
    "site_id",
    "name",
    "milestone_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Rename or re-date a milestone (both name and milestone_date are required). Needs a manage token for the site. POST /sites/{site_id}/milestones/{milestone_id}.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "milestone_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "The milestone id (a UUID, from fathom_list_milestones)."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30,
      "description": "Milestone name (up to 30 characters), e.g. Redesign launch."
    },
    "milestone_date": {
      "type": "string",
      "description": "The milestone's date, YYYY-MM-DD."
    }
  },
  "required": [
    "site_id",
    "milestone_id",
    "name",
    "milestone_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Permanently delete a milestone (only the annotation; traffic data is not touched). Cannot be undone. Needs a manage token for the site. DELETE /sites/{site_id}/milestones/{milestone_id}.

{
  "type": "object",
  "properties": {
    "site_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them."
    },
    "milestone_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "description": "The milestone id (a UUID, from fathom_list_milestones)."
    }
  },
  "required": [
    "site_id",
    "milestone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}