GA4 MCP Sever

GA4 MCP服务器

一个模块化、可维护的Google Analytics 4 MCP（模型上下文协议）服务器，遵循干净代码原则构建。

🏃‍♂️ 入门指南

先决条件

为了能够使用您自己的MCP服务器实例，您需要创建自己的Google凭据并获取客户端ID和客户端密钥。 创建步骤 谷歌云客户端信誉

获得客户端ID和客户端Seceret后，将它们添加到.env.example文件中，然后将名称更改为.env

快速开始

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GA4_CLIENT_ID="your_client_id"
export GA4_CLIENT_SECRET="your_client_secret"

# Run the server
fastmcp run app.py:mcp

将MCP安装到Claude桌面

fastmcp install app.py:mcp

🏗️ 架构概述

该应用程序已从一个734行的文件完全重构为模块化架构：

backend/
├── src/                           # Main application code
│   ├── auth/                      # Authentication modules
│   │   ├── oauth_manager.py       # OAuth flow management
│   │   └── credentials_manager.py # Credential storage/retrieval
│   ├── analytics/                 # GA4 data processing
│   │   ├── ga4_client.py         # GA4 API client wrapper
│   │   ├── report_builder.py     # Request building logic
│   │   └── data_formatter.py     # Response formatting
│   ├── config/                   # Configuration management
│   │   ├── settings.py           # Environment variable handling
│   │   └── constants.py          # Application constants
│   ├── utils/                    # Utility modules
│   │   ├── errors.py             # Custom exception classes
│   │   ├── logging.py            # Logging configuration
│   │   └── validation.py         # Input validation
│   ├── server.py                 # FastMCP server setup
│   └── main.py                   # Application entry point
├── tests/                        # Organized test suite
│   ├── conftest.py              # Shared test fixtures
│   ├── test_auth/               # Authentication tests
│   ├── test_analytics/          # Analytics tests
│   └── test_integration/        # End-to-end tests
├── app_refactored.py            # Backward compatibility wrapper
└── requirements.txt

🚀 主要特点

认证管理

# OAuth flow management
oauth_manager = OAuthManager(settings, credentials_manager)
auth_url = oauth_manager.start_oauth_flow()
credentials = oauth_manager.complete_oauth_flow(auth_code)

# Credential persistence
credentials_manager = CredentialsManager()
credentials_manager.save_credentials(creds)
loaded_creds = credentials_manager.load_credentials()

分析数据检索

# GA4 client with validation
ga4_client = GA4Client(credentials)
report = ga4_client.get_standard_report(
    property_id="123456789",
    start_date="7daysAgo",
    end_date="today",
    metrics="sessions,users",
    dimensions="date"
)

配置管理

# Centralized settings
settings = Settings()
client_config = settings.get_oauth_client_config()
debug_info = settings.get_debug_info()

🧪 测试结构

组织测试套件

• 单元测试：单个模块测试
• 集成测试：端到端工作流测试
• 夹具：中的可重用测试数据和模拟 conftest.py
• 覆盖：所有模块的全面测试覆盖

运行测试

# Run all tests
pytest

# Run specific test module
pytest tests/test_auth/

# Run with coverage
pytest --cov=src tests/

🛠️ 开发指南

添加新功能

1. 识别模块：确定该功能属于哪个模块
2. 遵循模式：使用现有模式进行错误处理、日志记录和验证
3. 编写测试：在适当的测试目录中添加综合测试
4. 更新文档：添加文档字符串，并在需要时更新README

代码规范

• 类型提示：所有公共方法都必须有类型提示
• Docstrings 的：所有公共方法都必须具有描述性文档字符串
• 错误处理：使用自定义例外 utils.errors
• 日志记录：使用结构化日志记录 utils.logging
• 验证：使用验证所有输入 utils.validation

📈 未来的增强功能

模块化架构使扩展变得容易：

• 新的分析功能：添加到 analytics/ 模块
• 其他身份验证方法：扩展 auth/ 模块
• 增强验证：展开 utils/validation.py
• 更好的错误处理：将特定错误类型添加到 utils/errors.py
• 缓存：添加缓存层以提高性能
• 速率限制：实施API速率限制