https://github.com/mackenly/mcp-fathom-analytics
MCP server for Fathom Analytics
https://github.com/mackenly/mcp-fathom-analytics
fathom-analytics mcp mcp-server
Last synced: 5 days ago
JSON representation
MCP server for Fathom Analytics
- Host: GitHub
- URL: https://github.com/mackenly/mcp-fathom-analytics
- Owner: mackenly
- License: mit
- Created: 2025-03-07T22:12:27.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-03-12T15:32:22.000Z (about 1 month ago)
- Last Synced: 2025-04-05T11:55:44.473Z (11 days ago)
- Topics: fathom-analytics, mcp, mcp-server
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/mcp-fathom-analytics
- Size: 27.3 KB
- Stars: 1
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - Fathom Analytics - Access and analyze Fathom Analytics data and reports (Community Servers)
- Awesome-MCP-Servers-directory - Fathom Analytics - Access and analyze Fathom Analytics data and reports (Research & Data)
- awesome-mcp-servers - Fathom Analytics - Access Fathom Analytics data and reports about your sites (🎯 <a name="marketing"></a>Marketing)
- awesome-mcp-servers - Fathom Analytics - MCP server for Fathom Analytics (Table of Contents / Other Tools and Integrations)
- awesome-mcp-servers - Fathom Analytics - MCP server for Fathom Analytics (Table of Contents / Other Tools and Integrations)
README
# MCP Fathom Analytics
An unofficial Model Context Protocol ([MCP](https://modelcontextprotocol.io/introduction)) server for accessing [Fathom Analytics](https://usefathom.com/) data through an AI assistant. This implementation uses the [@mackenly/fathom-api](https://github.com/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](https://www.npmjs.com/package/mcp-fathom-analytics).
## Features
The MCP server provides the following Fathom Analytics tools:
### Account Information
- `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](https://modelcontextprotocol.io/quickstart/user)). Here's an example:
```json
{
"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](https://modelcontextprotocol.io/clients)
## API Structure
The MCP server uses the [@mackenly/fathom-api](https://github.com/mackenly/fathom-api) SDK to interface with the 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 use cases:
1. **Daily pageview statistics for the last 30 days**:
```json
{
"entity": "pageview",
"entity_id": "SITE_ID",
"aggregates": "pageviews,uniques,visits",
"date_grouping": "day",
"date_from": "2023-08-01 00:00:00"
}
```
2. **Performance of individual pages**:
```json
{
"entity": "pageview",
"entity_id": "SITE_ID",
"aggregates": "pageviews,uniques,avg_duration",
"field_grouping": "pathname",
"sort_by": "pageviews:desc",
"limit": 10
}
```
3. **Traffic from specific countries**:
```json
{
"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.