MCP Fathom Analytics

🚀 MCP Fathom Analytics Server

This is an unofficial implementation of the Model Context Protocol (MCP) server, designed to access Fathom Analytics data via an AI assistant. It uses the unofficial @mackenly/fathom-api SDK to interact with the Fathom Analytics API. This project is not endorsed, supported, or authorized by Fathom Analytics. It has been published as an npx script on npm.

✨ Features

This MCP server provides the following Fathom Analytics tools:

Account Information

• get-account: Retrieve details of your Fathom Analytics account.

Site 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: Obtain real-time data about current site visitors.

🚀 Quick Start

If you're using Claude Desktop, you can add this MCP server by using a JSON configuration (for more information, see the Quick Start Guide). 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 at the Model Context Protocol Example Clients.

📚 Documentation

API Structure

This MCP server uses the @mackenly/fathom-api SDK interface to interact with the following Fathom Analytics API endpoints:

1. Account API: https://api.usefathom.com/v1/account
2. Sites API: https://api.usefathom.com/v1/sites
3. Events API: https://api.usefathom.com/v1/sites/SITE_ID/events
4. Aggregation API: https://api.usefathom.com/v1/aggregations
5. Current Visitors API: https://api.usefathom.com/v1/current_visitors

Aggregation Examples

The aggregation tool is highly flexible. Here are some example usages:

Basic Usage

{
  "entity": "pageview",
  "entity_id": "SITE_ID",
  "aggregates": "pageviews,uniques,visits",
  "date_grouping": "day",
  "date_from": "2023-08-01 00:00:00"
}

This example shows how to get the daily page views in the past 30 days.

Advanced Usage

{
  "entity": "pageview",
  "entity_id": "SITE_ID",
  "aggregates": "pageviews,uniques,avg_duration",
  "field_grouping": "pathname",
  "sort_by": "pageviews:desc",
  "limit": 5
}

This example demonstrates how to analyze the performance of specific pages.

{
  "entity": "event",
  "entity_id": "SITE_ID",
  "aggregates": "count",
  "field_grouping": "geo.country_code",
  "filter": {
    "properties": {
      "event_type": "page_view"
    }
  }
}

This example shows how to analyze traffic from specific countries.

🤝 Contribution

Contributions to this project are welcome! Please refer to CONTRIBUTING.md for guidance on how to contribute.

📄 License

This project is licensed under the MIT License. For more information, see LICENSE.

📞 Contact

If you have any questions or feedback, please contact us via Contact Information.