Google Analytics MCP Server
An MCP server implementation for accessing Google Analytics 4 (GA4) data, built using the Model Context Protocol
TypeScript SDK.
Features
- Get page view metrics with customizable dimensions
- Track active and new users over time
- Analyze specific events and their metrics
- Monitor user behavior metrics (session duration, bounce rate)
- Flexible date range selection for all queries
Prerequisites
- Node.js 20 or higher
- A Google Analytics 4 property.
- A Google Cloud project with the Analytics Data API enabled.
- A service account with credentials to access the API.
Setup and Configuration
To use this server, you need to configure authentication with Google Analytics. This is done using a service account.
1. Enable the Google Analytics Data API
- Go to the Google Cloud Console.
- Select the project you want to use.
- In the navigation menu, go to APIs & Services > Library.
- Search for "Google Analytics Data API" and enable it.
2. Create a Service Account
- In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
- Click "Create Service Account".
- Give the service account a name (e.g., "GA4 MCP Server").
- Click "Create and Continue".
- You can skip granting the service account access to the project.
- Click "Done".
- Find the service account you just created and click on the three dots under "Actions".
- Select "Manage keys", then "Add Key" > "Create new key".
- Choose JSON as the key type and click "Create". A JSON file with the credentials will be downloaded.
3. Grant Service Account Access to Google Analytics
- Open Google Analytics.
- Navigate to the Admin section of your GA4 property.
- Under the Property column, click on Property Access Management.
- Click the "+" button to add a new user.
- In the "Email address" field, paste the
client_email from the JSON credentials file you downloaded. - Assign the "Viewer" role. You do not need to notify the user.
- Click "Add".
4. Set Environment Variables
The server requires the following environment variables:
GOOGLE_CLIENT_EMAIL: The client_email from your service account JSON file.GOOGLE_PRIVATE_KEY: The private_key from your service account JSON file.GA_PROPERTY_ID: Your Google Analytics 4 property ID.
You can set them in your environment or use a .env file.
export GOOGLE_CLIENT_EMAIL="your-service-account@your-project.iam.gserviceaccount.com"
export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
export GA_PROPERTY_ID="your_property_id"
Installation
Installing via Smithery
To install Google Analytics Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mcp-server-google-analytics --client claude
Manual Installation
npm install -g mcp-server-google-analytics
Or use with npx directly:
npx mcp-server-google-analytics
Usage
Starting the Server
Configuration in Claude Desktop
Add this to your Claude Desktop configuration:
{
"mcpServers": {
"google-analytics": {
"command": "npx",
"args": ["-y", "mcp-server-google-analytics"],
"env": {
"GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
"GOOGLE_PRIVATE_KEY": "your-private-key",
"GA_PROPERTY_ID": "your-ga4-property-id"
}
}
}
}
Available Functions
runReport
Run a flexible report to get analytics data.
Input:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"dimensions": [{ "name": "country" }, { "name": "city" }],
"metrics": [{ "name": "activeUsers" }, { "name": "newUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"stringFilter": {
"value": "United States"
}
}
}
}
getPageViews
Get page view metrics for a specific date range:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"dimensions": ["page", "country"] // Optional
}
getActiveUsers
Get active users metrics:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
getEvents
Get event metrics:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"eventName": "purchase" // Optional
}
getUserBehavior
Get user behavior metrics:
{
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
Security Considerations
- Least Privilege: Only grant the service account the "Viewer" role in Google Analytics.
- Key Management: Keep your service account key file secure and do not expose it in client-side code.
- Environment Variables: Use environment variables to store sensitive information like the client email, private key, and property ID.
Contributing
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and
the process for submitting pull requests.
License
This project is licensed under the MIT License - see the LICENSE file for details.