Amplitude MCP 服务器

一个用于将 Amplitude 分析集成到 AI 工作流中的 模型上下文协议 (MCP) 服务器。该服务器允许像 Claude 这样的 AI 助手在 Amplitude 中跟踪事件、页面浏览、用户注册、设置用户属性以及跟踪收入。

版本 1.0.1 注意事项： 工具名称现在包含 amplitude_ 前缀，以防止与其他分析 MCP 服务器的命名空间冲突。

目录

• 特性
• 安装
• 快速开始
• 详细用法
  • 与 Claude 桌面版配合使用
  • 与其他 MCP 客户端配合使用
• 工具参考
• 示例
• 故障排除
• 安全注意事项
• 贡献
• 许可证

特性

• 在 Amplitude 中跟踪自定义事件
• 跟踪带有属性的页面浏览
• 跟踪用户注册并创建用户档案
• 更新现有用户属性
• 跟踪收入和购买
• 与 Claude 桌面版及其他 MCP 客户端简单集成

安装

前提条件

• Node.js 16 或更高版本
• 一个 Amplitude API 密钥（通过在 Amplitude 注册获取）

NPM 安装（推荐）

# Install globally
npm install -g amplitude-mcp-server

# Or use directly with npx
npx amplitude-mcp-server --api-key YOUR_AMPLITUDE_API_KEY

手动安装

# Clone the repository
git clone https://github.com/ciaraadkins/amplitude-mcp-server.git
cd amplitude-mcp-server

# Install dependencies
npm install

# Run the server
node index.js --api-key YOUR_AMPLITUDE_API_KEY

快速开始

要开始使用 Claude 桌面版上的 Amplitude MCP 服务器：

1. 确保您的机器上已安装 Claude 桌面版（从 claude.ai/download 下载）

2. 创建或编辑 Claude 桌面配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %AppData%\Claude\claude_desktop_config.json

3. 添加 Amplitude MCP 服务器配置：

{
  "mcpServers": {
    "amplitude-analytics": {
      "command": "npx",
      "args": [
        "-y",
        "amplitude-mcp-server",
        "--api-key",
        "YOUR_AMPLITUDE_API_KEY"
      ]
    }
  }
}

1. 重启 Claude 桌面版并开始跟踪分析数据！

详细用法

与 Claude 桌面版配合使用

按照快速开始部分所示设置配置文件后，您可以在与 Claude 的对话中直接使用 Amplitude 分析功能。

您可以使用的提示示例包括：

• "为用户'user123'在 Amplitude 中跟踪名为'document_generated'的自定义事件"
• "在 Amplitude 中跟踪定价页面的页面浏览"
• "在 Amplitude 中为 John Doe 创建新用户档案，电子邮件为 john@example.com"
• "在 Amplitude 中更新用户'user123'的用户档案信息"
• "在 Amplitude 中跟踪产品 X 的 $49.99 购买"

Claude 将根据您的请求使用适当的 Amplitude MCP 工具。

与其他 MCP 客户端配合使用

此服务器使用标准的 Model Context Protocol，可以与任何 MCP 客户端集成：

1. 启动服务器：

   npx amplitude-mcp-server --api-key YOUR_AMPLITUDE_API_KEY
   

2. 使用 stdio 传输方式将您的 MCP 客户端连接到服务器

3. 客户端可以发现并使用可用工具（track_event, track_pageview, track_signup, set_user_properties, track_revenue）

工具参考

Amplitude MCP 服务器提供了以下工具：

amplitude_track_event

在 Amplitude 中跟踪自定义事件。

参数：

• event_name (字符串, 必填): 要跟踪的事件名称
• user_id (字符串, 可选): 用户标识符
• device_id (字符串, 可选): 设备标识符
• properties (对象, 可选): 随事件跟踪的附加属性
• user_properties (对象, 可选): 通过此事件更新的用户属性

注意： 必须提供 user_id 或 device_id 中的一个。

示例：

{
  "event_name": "button_clicked",
  "user_id": "user123",
  "properties": {
    "button_id": "submit_form",
    "page": "checkout"
  },
  "user_properties": {
    "last_action": "form_submit"
  }
}

amplitude_track_pageview

在 Amplitude 中跟踪页面浏览事件。

参数：

• page_name (字符串, 必填): 查看的页面名称
• user_id (字符串, 可选): 用户标识符
• device_id (字符串, 可选): 设备标识符
• properties (对象, 可选): 随事件跟踪的附加属性

注意： 必须提供 user_id 或 device_id 中的一个。

示例：

{
  "page_name": "homepage",
  "user_id": "user123",
  "properties": {
    "referrer": "google.com",
    "duration": 120
  }
}

amplitude_track_signup

跟踪注册事件并在 Amplitude 中创建用户档案。

参数：

• user_name (字符串, 必填): 用户全名
• email (字符串, 必填): 用户电子邮件地址
• plan (字符串, 可选): 注册计划。默认为 'free'

示例：

{
  "user_name": "John Doe",
  "email": "john@example.com",
  "plan": "premium"
}

amplitude_set_user_properties

在 Amplitude 中更新用户的档案属性。

参数：

• user_id (字符串, 必填): 用户标识符
• properties (对象, 必填): 要设置的档案属性

示例：

{
  "user_id": "user123",
  "properties": {
    "name": "John Doe",
    "email": "john@example.com",
    "plan": "premium",
    "company": "Acme Inc"
  }
}

amplitude_track_revenue

在 Amplitude 中跟踪收入事件。

参数：

• user_id (字符串, 必填): 用户标识符
• product_id (字符串, 必填): 购买的商品标识符
• price (数字, 必填): 购买商品的价格
• quantity (数字, 可选): 购买的数量。默认值为 1
• revenue_type (字符串, 可选): 收入类型（例如，'purchase', 'refund', 'subscription'）

示例：

{
  "user_id": "user123",
  "product_id": "premium_plan",
  "price": 49.99,
  "quantity": 1,
  "revenue_type": "subscription"
}

示例

这里有一些使用 Claude 的 Amplitude MCP 服务器的实际例子：

跟踪按钮点击

You: Can you track an event in Amplitude when a user clicks the submit button?

Claude: I'll track that event for you. Let me use the Amplitude analytics tool.

[Claude uses the amplitude_track_event tool with appropriate parameters]

Claude: I've successfully tracked the 'button_clicked' event in Amplitude with the properties you specified.

创建用户档案

You: Create a new user profile in Amplitude for Sarah Johnson who signed up with sarah@example.com on the premium plan.

Claude: I'll create that user profile in Amplitude.

[Claude uses the amplitude_track_signup tool with appropriate parameters]

Claude: I've successfully tracked the signup for Sarah Johnson and created a profile in Amplitude with the premium plan.

跟踪收入

You: Track a purchase of our premium plan for $99.99 by user12345.

Claude: I'll track that revenue event in Amplitude.

[Claude uses the amplitude_track_revenue tool with appropriate parameters]

Claude: I've successfully tracked revenue of $99.99 for the premium plan purchase by user12345.

故障排除

常见问题

1. 服务器无法启动：

   • 确保您提供的 Amplitude API 密钥有效
   • 检查 Node.js 是否已安装且版本为 16 或更高

2. Claude Desktop 不显示 Amplitude 工具：

   • 验证您的 claude_desktop_config.json 文件语法是否正确
   • 确保在编辑配置后重启了 Claude Desktop
   • 检查服务器路径是否正确

3. 事件未出现在 Amplitude 中：

   • 验证您的 Amplitude API 密钥是否正确
   • 检查 Amplitude 项目设置以确保正在接收数据
   • 事件可能需要几分钟才能出现在 Amplitude 界面中

调试模式

要以调试模式运行服务器以获取更详细的日志：

npx amplitude-mcp-server --api-key YOUR_AMPLITUDE_API_KEY --debug

安全注意事项

• 您的 Amplitude API 密钥存储在 Claude Desktop 配置文件中。请确保该文件具有适当的权限。
• 在生产环境中，请考虑使用环境变量来处理敏感令牌。
• 该服务器未实现速率限制 - 请为生产使用考虑增加额外的安全措施。
• 事件直接发送到 Amplitude 的 API - 请查看 Amplitude 的隐私政策以了解数据处理实践。

贡献

欢迎贡献！请随时提交 Pull Request。

1. 叉分仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 将更改推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

本项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。