# MCP Google Analytics 4 Server
A comprehensive Model Context Protocol (MCP) server for Google Analytics 4 integration, providing advanced analytics capabilities for AI applications.
## 🎯 Overview
This MCP server enables AI applications to interact with Google Analytics 4 through a standardized protocol. It supports data retrieval, configuration management, compliance features, and business intelligence automation.
**Compatibility**: Works with Cursor, Claude Desktop, and any MCP-compatible AI platform.
## 📊 Features
### Phase 1: Advanced Reporting (8 tools)
- **Basic Metrics**: Core GA4 metrics and KPIs
- **Traffic Analysis**: Sources, pages, and user behavior
- **Real-time Reports**: Live data (up to 29 minutes for standard properties)
- **Pivot Reports**: Cross-dimensional analysis
- **Funnel Analysis**: Conversion path tracking
- **Batch Processing**: Multiple reports automation
### Phase 2: Configuration Management (13 tools)
- **Custom Dimensions**: Create, read, update, archive
- **Custom Metrics**: Complete lifecycle management
- **Conversion Events**: Configure and manage goals
- **Property Settings**: Comprehensive configuration access
### Phase 3: Platform Integrations (15 tools)
- **Google Ads**: Campaign performance and attribution
- **BigQuery**: Data warehouse connectivity
- **Data Streams**: Multi-platform tracking setup
- **Measurement Protocol**: Server-side event tracking
### Phase 4: Compliance & Privacy (10 tools)
- **GDPR Compliance**: Automated data subject rights
- **User Deletion**: Privacy-compliant data removal
- **Data Retention**: Automated lifecycle management
- **Access Control**: Permission and audit management
### Phase 5: Business Intelligence (8 tools)
- **Attribution Modeling**: Multi-touch attribution analysis
- **Audience Management**: Automated segmentation
- **Predictive Analytics**: ML-powered insights
- **Custom Dashboards**: Automated reporting
**Total: 54 specialized tools across 5 phases**
## 🔧 Installation
### Prerequisites
- Python 3.8+
- Google Analytics 4 property
- Google Cloud project with Analytics API enabled
### Quick Setup
1. **Install the package**:
```bash
pip install mcp-ga4-ultimate
```
2. **Configure authentication**:
```bash
# Set up Application Default Credentials
gcloud auth application-default login \
--scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/analytics.edit
```
3. **Add to your MCP client**:
**For Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"ga4-ultimate": {
"command": "python",
"args": ["-m", "mcp_ga4_ultimate"],
"env": {
"GOOGLE_ANALYTICS_PROPERTY_ID": "your_property_id"
}
}
}
}
```
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"ga4-ultimate": {
"command": "python",
"args": ["-m", "mcp_ga4_ultimate"],
"env": {
"GOOGLE_ANALYTICS_PROPERTY_ID": "your_property_id"
}
}
}
}
```
## 🚀 Usage Examples
### Basic Analytics Query
```
"Show me the top 10 pages by traffic in the last 30 days"
```
### Real-time Monitoring
```
"What's happening on my website right now? Show active users and top content"
```
### Conversion Analysis
```
"Analyze the funnel from landing page to purchase completion"
```
### Configuration Management
```
"Create a custom dimension for tracking user engagement score"
```
### GDPR Compliance
```
"Process data deletion request for user ID abc123"
```
## 📋 API Coverage
This server implements comprehensive coverage of Google Analytics APIs:
| API | Coverage | Tools |
|-----|----------|-------|
| **Analytics Data API** | Complete | 15 tools |
| **Analytics Admin API** | Complete | 27 tools |
| **Analytics Measurement Protocol** | Complete | 8 tools |
| **User Deletion API** | Complete | 4 tools |
**Total API Coverage**: 54 specialized tools
## 🔒 Security & Permissions
### Required OAuth Scopes
- `https://www.googleapis.com/auth/analytics.readonly` - Data access
- `https://www.googleapis.com/auth/analytics.edit` - Configuration management
- `https://www.googleapis.com/auth/analytics.manage.users` - User management
### Data Privacy
- No data stored locally
- Direct API communication only
- GDPR-compliant data handling
- Audit logging for compliance
## 🧪 Testing & Validation
The server includes comprehensive testing:
- **Unit Tests**: All 54 tools tested individually
- **Integration Tests**: Real API validation
- **Success Rate**: 92.3% (50/54 tools passing)
- **Error Handling**: Graceful fallbacks and detailed error messages
Run tests:
```bash
python -m pytest tests/ -v
```
## 📖 Documentation
### Complete API Reference
- [Tool Documentation](docs/tools.md) - All 54 tools detailed
- [Configuration Guide](docs/configuration.md) - Setup and customization
- [Examples](docs/examples.md) - Common use cases
- [Troubleshooting](docs/troubleshooting.md) - Common issues
### Development
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Architecture](docs/architecture.md) - Technical design
- [Testing](docs/testing.md) - Test suite details
## 🆚 Comparison with Other Solutions
| Feature | This Server | Google Official MCP | Basic Packages |
|---------|-------------|-------------------|----------------|
| **Total Tools** | 54 | 6 | 2-3 |
| **Platform Support** | Universal MCP | Gemini only | Varies |
| **Real-time Data** | ✅ Advanced | ✅ Basic | ❌ |
| **Configuration Management** | ✅ Complete | ❌ | ❌ |
| **GDPR Compliance** | ✅ Built-in | ❌ | ❌ |
| **Business Intelligence** | ✅ Automated | ❌ | ❌ |
| **Write Permissions** | ✅ Full | ❌ Read-only | Varies |
| **Multi-touch Attribution** | ✅ Advanced | ❌ | ❌ |
| **Testing Coverage** | ✅ 92.3% | Unknown | Minimal |
## 🤝 Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/your-org/mcp-ga4-ultimate.git
cd mcp-ga4-ultimate
pip install -e .[dev]
```
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🔗 Links
- [Google Analytics 4 Documentation](https://developers.google.com/analytics/devguides/reporting/data/v1)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [Issue Tracker](https://github.com/your-org/mcp-ga4-ultimate/issues)
## 📞 Support
- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](https://github.com/your-org/mcp-ga4-ultimate/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/mcp-ga4-ultimate/discussions)
---
**Note**: This is an independent implementation. For the official Google Analytics MCP server, see [googleanalytics/google-analytics-mcp](https://github.com/googleanalytics/google-analytics-mcp).
