An unofficial Model Context Protocol (MCP) server for accessing Fathom Analytics data through an AI assistant. This implementation uses the @mackenly/fathom-api unofficial SDK to interact with the Fathom Analytics API. Not affiliated, endorsed, or supported by Fathom Analytics. Published to npm as an npx script.
Features
The MCP server provides the following Fathom Analytics tools:
get-account: Retrieve details about your Fathom Analytics account
Sites Management
list-sites: List all your Fathom Analytics sites
Events
list-events: List events for a specific site
Analytics
get-aggregation: Generate aggregated analytics reports with flexible filtering and grouping options
Visitor Tracking
get-current-visitors: Get real-time data about current site visitors
Usage
If you're using Claude Desktop, you can add the MCP server using the json config (more info). Here's an example:
{
"mcpServers": {
"fathom-analytics": {
"command": "npx",
"args": [
"-y",
"mcp-fathom-analytics"
],
"env": {
"FATHOM_API_KEY": "your_api_key_here"
}
}
}
}
You can find more information about other MCP Clients here: Model Context Protocol Example Clients
API Structure
The MCP server uses the @mackenly/fathom-api SDK to interface with the Fathom Analytics API endpoints:
- Account API:
https://api.usefathom.com/v1/account
- Sites API:
https://api.usefathom.com/v1/sites
- Events API:
https://api.usefathom.com/v1/sites/SITE_ID/events
- Aggregation API:
https://api.usefathom.com/v1/aggregations
- Current Visitors API:
https://api.usefathom.com/v1/current_visitors
Aggregation Examples
The aggregation tool is highly flexible. Here are some example use cases:
-
Daily pageview statistics for the last 30 days:
{
"entity": "pageview",
"entity_id": "SITE_ID",
"aggregates": "pageviews,uniques,visits",
"date_grouping": "day",
"date_from": "2023-08-01 00:00:00"
}
-
Performance of individual pages:
{
"entity": "pageview",
"entity_id": "SITE_ID",
"aggregates": "pageviews,uniques,avg_duration",
"field_grouping": "pathname",
"sort_by": "pageviews:desc",
"limit": 10
}
-
Traffic from specific countries:
{
"entity": "pageview",
"entity_id": "SITE_ID",
"aggregates": "visits",
"field_grouping": "country_code",
"sort_by": "visits:desc"
}
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
[
{
"description": "Get Fathom Analytics account information",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "get-account"
},
{
"description": "List all Fathom Analytics sites on the account",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"limit": {
"description": "Optional limit on the number of sites to return",
"exclusiveMinimum": 0,
"type": "number"
}
},
"type": "object"
},
"name": "list-sites"
},
{
"description": "List all events for a Fathom Analytics site (automatically handles pagination)",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"limit": {
"description": "Optional limit on the number of events to return",
"exclusiveMinimum": 0,
"type": "number"
},
"site_id": {
"description": "ID of the site to retrieve events for",
"type": "string"
}
},
"required": [
"site_id"
],
"type": "object"
},
"name": "list-events"
},
{
"description": "Get aggregated analytics data from Fathom",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"aggregates": {
"description": "Comma-separated list of aggregates to include (visits,uniques,pageviews,avg_duration,bounce_rate,conversions,unique_conversions,value)",
"type": "string"
},
"date_from": {
"description": "Start date (e.g., 2025-01-01 00:00:00 or 2025-01-01)",
"type": "string"
},
"date_grouping": {
"description": "Optional date grouping",
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
},
"date_to": {
"description": "End date (e.g., 2025-12-31 23:59:59 or 2025-12-31)",
"type": "string"
},
"entity": {
"description": "The entity to aggregate (pageview or event)",
"enum": [
"pageview",
"event"
],
"type": "string"
},
"entity_id": {
"description": "ID of the entity (site ID or event ID)",
"type": "string"
},
"field_grouping": {
"description": "Comma-separated fields to group by (e.g., hostname,pathname)",
"type": "string"
},
"filters": {
"description": "Array of filter objects",
"items": {
"additionalProperties": false,
"properties": {
"operator": {
"enum": [
"is",
"is not",
"is like",
"is not like"
],
"type": "string"
},
"property": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"property",
"operator",
"value"
],
"type": "object"
},
"type": "array"
},
"limit": {
"description": "Limit on number of results",
"exclusiveMinimum": 0,
"type": "number"
},
"sort_by": {
"description": "Field to sort by (e.g., pageviews:desc)",
"type": "string"
},
"timezone": {
"description": "Timezone for date calculations (default: UTC)",
"type": "string"
}
},
"required": [
"entity",
"entity_id",
"aggregates",
"date_from",
"date_to"
],
"type": "object"
},
"name": "get-aggregation"
},
{
"description": "Get current visitors for a Fathom Analytics site",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"detailed": {
"description": "Whether to include detailed content and referrer information",
"type": "boolean"
},
"site_id": {
"description": "ID of the site to retrieve current visitors for",
"type": "string"
}
},
"required": [
"site_id"
],
"type": "object"
},
"name": "get-current-visitors"
}
]