技术文档摘要

🤖 Piwik PRO MCP Server (测试版)

使用官方MCP Python SDK构建的Model Context Protocol (MCP)服务器，提供控制Piwik PRO Analytics资源的能力。

🎇 功能

• 应用管理：创建、读取、更新和删除应用
• 分析：
  • 注释
    • 创建、读取、更新和删除注释
• 跟踪器设置：全局和特定于应用的跟踪器配置管理
• 容器设置：
  • 获取应用的安装代码
  • 读取容器设置
• 客户数据平台：
  • 创建、读取、更新和删除受众群体
• 标签管理支持：创建、读取、更新和删除：
  • 标签
    • 自定义代码
    • 自定义事件
  • 触发器
    • 点击
    • 数据层事件
    • 页面视图
  • 变量
    • 常量
    • 自定义JavaScript
    • 数据层
    • DOM元素
  • 版本管理：
    • 发布标签管理器版本

🚀 快速开始

访问您的账户API密钥部分：https://ACCOUNT.piwik.pro/profile/api-credentials 并生成新的凭据。您需要这三个变量用于MCP配置：

• PIWIK_PRO_HOST - 您的piwik主机，ACCOUNT.piwik.pro
• PIWIK_PRO_CLIENT_ID - 客户端ID
• PIWIK_PRO_CLIENT_SECRET - 客户端密钥

MCP客户端配置

所有MCP客户端都有一个专门的json文件来存储MCP配置。根据客户端的不同，名称和位置可能会有所不同。

• Claude Desktop

  • 转到 设置 -> 开发者 -> 编辑配置 - 这将打开包含 claude_desktop_config.json 的目录
  • 应用以下片段之一
  • 重启应用程序

• Cursor - 官方文档

• Claude Code - 官方文档

要使用Piwik PRO MCP服务器，您需要安装 uv 或 docker。

复制您首选选项的配置并填写所需的环境变量。

选项 #1 - UV

如果您没有安装 uv，请查看 官方安装指南。

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "uvx",
      "args": ["piwik-pro-mcp"],
      "env": {
        "PIWIK_PRO_HOST": "ACCOUNT.piwik.pro",
        "PIWIK_PRO_CLIENT_ID": "CLIENT_ID",
        "PIWIK_PRO_CLIENT_SECRET": "CLIENT_SECRET"
      }
    }
  }
}

<details> <summary><b>🔒 如何将秘密信息保留在配置文件之外</b></summary>

直接在MCP配置中键入环境变量更容易，但将其放在文件外是一种更安全的方式。创建 .piwik-pro-mcp.env 文件并将配置放入其中：

# .piwik.pro.mcp.env 
PIWIK_PRO_HOST=ACCOUNT.piwik.pro
PIWIK_PRO_CLIENT_ID=_CLIENT_ID_
PIWIK_PRO_CLIENT_SECRET=CLIENT_SECRET

通过 --env-file 参数引用此文件：

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "uvx",
      "args": [
        "piwik-pro-mcp", 
        "--env-file", 
        "/absolute/path/to/.piwik-pro-mcp.env"
      ]
    }
  }
}

</details>

选项 #2 - Docker

您需要安装Docker - 查看 官方安装指南。

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/piwikpro/mcp:latest"
      ],
      "env": {
        "PIWIK_PRO_HOST": "ACCOUNT.piwik.pro",
        "PIWIK_PRO_CLIENT_ID": "CLIENT_ID",
        "PIWIK_PRO_CLIENT_SECRET": "CLIENT_SECRET"
      }
    }
  }
}

<details> <summary><b>🔒 如何将秘密信息保留在配置文件之外</b></summary>

直接在MCP配置中键入环境变量更容易，但将其放在文件外是一种更安全的方式。创建 .piwik-pro-mcp.env 文件并将配置放入其中：

# .piwik.pro.mcp.env 
PIWIK_PRO_HOST=ACCOUNT.piwik.pro
PIWIK_PRO_CLIENT_ID=CLIENT_ID
PIWIK_PRO_CLIENT_SECRET=CLIENT_SECRET

通过 --env-file 参数引用此文件：

{
  "mcpServers": {
    "piwik-pro-analytics": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/.piwik-pro-mcp.env",
        "ghcr.io/piwikpro/mcp:latest"
      ]
    }
  }
}

</details>

重启您的MCP客户端以应用配置更改。

🪄 首次使用

⚠️ 小心操作

请注意，AI生成的结果有时可能出乎意料或不一致。重要的是仔细审查和验证任何输出，因为AI生成的解决方案可能并不总是完全符合您的要求或最佳实践。

初始提示

配置完成后，您可以开始编写关于Piwik PRO资源的提示🎉。这里有一些示例，您可以测试集成是否正确工作。

列出我的Piwik PRO应用。

列出<NAME>应用的标签。

在<NAME>的应用中，添加一个新的标签，当用户进入任何页面时显示alert("hello")。

从应用<APP>中复制<NAME>的标签到所有带有<PREFIX>前缀的应用。

🚦 发展路线图

当前的功能集尚未完成，我们计划很快添加更多功能：

模块	功能	预计时间
分析	注释	已完成！
	目标	2025年第四季度
	自定义维度	2025年第四季度
	查询API	2025年第四季度

🔈 反馈

我们重视您的反馈和问题！如果您有任何建议、遇到任何问题或希望请求新功能，请在我们的 GitHub Issues页面 上提交问题。您的意见有助于我们改进项目并更好地服务社区。

📡遥测

我们收集匿名遥测数据，以帮助我们了解MCP服务器的使用情况，并提高其可靠性和功能。这些遥测包括有关调用哪些MCP工具以及响应结果（成功或错误）的信息，但不包括任何个人数据、工具参数或敏感信息。

收集的数据仅用于识别问题、优先考虑改进措施，并确保所有用户的最佳体验。

如果您不想发送遥测数据，可以在任何时候通过在MCP服务器配置中添加环境变量 PIWIK_PRO_TELEMETRY=0 来选择退出。

🔧 可用工具

参数发现

• tools_parameters_get(tool_name) - 获取任何工具参数的JSON模式

应用管理

• apps_list(limit, offset, search) - 列出所有应用，支持过滤和分页
• apps_get(app_id) - 获取特定应用的详细信息
• apps_create(attributes) - 使用JSON属性创建新应用
• apps_update(app_id, attributes) - 使用JSON属性更新现有应用
• apps_delete(app_id) - 删除应用（不可逆）

分析注释

• analytics_annotations_list(app_id, date_from, date_to, source, limit, offset) - 列出应用的注释；支持用户和系统注释。使用 source 进行筛选："all"、"user" 或 "system"。
• analytics_annotations_get(annotation_id, app_id) - 通过ID获取特定用户注释
• analytics_annotations_create(app_id, content, date, visibility) - 创建用户注释（默认可见性为"private"）
• analytics_annotations_update(annotation_id, app_id, content, date, visibility) - 更新现有用户注释（默认可见性为"private"）
• analytics_annotations_delete(annotation_id, app_id) - 通过ID删除用户注释

容器设置

• container_settings_get_installation_code(app_id) - 获取嵌入容器的安装代码片段
• container_settings_list(app_id) - 获取应用容器设置（带分页的JSON:API列表）

标签管理 - 标签

• tags_list(app_id, limit, offset, filters) - 列出标签
• tags_get(app_id, tag_id) - 获取特定标签的详细信息
• tags_create(app_id, attributes) - 使用JSON属性创建新标签
• tags_update(app_id, tag_id, attributes) - 使用JSON属性更新现有标签
• tags_delete(app_id, tag_id) - 删除标签（不可逆）
• tags_copy(app_id, tag_id, target_app_id?, name?, with_triggers=false) - 在同一应用内或复制到另一个应用中的标签。支持可选重命名和复制附加触发器（设置 with_triggers=true）。

标签管理 - 关系

• tags_list_triggers(app_id, tag_id, limit, offset, sort, name, trigger_type) - 列出与标签关联的触发器
• triggers_list_tags(app_id, trigger_id, limit, offset, sort, name, is_active, template, consent_type, is_prioritized) - 列出分配给触发器的标签

标签管理 - 触发器

• triggers_list(app_id, limit, offset, filters) - 列出触发器
• triggers_get(app_id, trigger_id) - 获取特定触发器的详细信息
• triggers_create(app_id, attributes) - 使用JSON属性创建新触发器
• triggers_copy(app_id, trigger_id, target_app_id?, name?) - 在同一应用内复制触发器到另一个应用。支持可选重命名。

标签管理 - 变量

• variables_list(app_id, limit, offset, filters) - 列出变量
• variables_get(app_id, variable_id) - 获取特定变量的详细信息
• variables_create(app_id, attributes) - 使用JSON属性创建新变量
• variables_update(app_id, variable_id, attributes) - 使用JSON属性更新现有变量
• variables_copy(app_id, variable_id, target_app_id?, name?) - 在同一应用内或复制到另一个应用中的变量。支持可选重命名。

标签管理 - 支持的资源

标签模板：

• custom_tag - 用于自定义HTML/JavaScript/CSS代码注入的灵活异步标签

触发器模板：

• click - 具有元素目标和条件筛选的点击事件触发器
• page_view - 具有URL模式匹配和用户特征的页面加载触发器

变量模板：

• constant - 跨标签使用的可复用常量静态值变量
• custom_javascript - 使用自定义JavaScript代码执行的动态变量
• dom_element - 使用CSS选择器或XPath从DOM元素中提取值
• data_layer - 从数据层对象中读取值以增强跟踪数据

标签管理 - 模板发现

• templates_list() - 列出可用的标签模板
• templates_get_tag(template_name) - 获取标签模板的详细文档
• templates_list_triggers() - 列出可用的触发器模板
• templates_get_trigger(template_name) - 获取触发器模板的详细文档
• templates_list_variables() - 列出可用的变量模板
• templates_get_variable(template_name) - 获取变量模板的详细文档

注意：未来计划实现Google Analytics、Piwik PRO、电子商务跟踪和其他平台的额外模板。当前的模板为自定义跟踪实现提供了坚实的基础。

标签管理 - 版本

• versions_list(app_id, limit, offset) - 列出所有版本
• versions_get_draft(app_id) - 获取当前草稿版本
• versions_get_published(app_id) - 获取已发布/实时版本
• versions_publish_draft(app_id) - 发布草稿使其成为实时版本

客户数据平台(CDP)

• audiences_list(app_id) - 列出应用的所有受众群体
• audiences_get(app_id, audience_id) - 获取详细的受众群体信息
• audiences_create(app_id, attributes) - 使用JSON属性创建新受众群体
• audiences_update(app_id, audience_id, attributes) - 使用JSON属性更新现有受众群体
• audiences_delete(app_id, audience_id) - 删除受众群体（不可逆）
• activations_attributes_list(app_id) - 列出所有可用于创建受众群体的CDP属性

跟踪器设置

• tracker_settings_global_get() - 获取全局跟踪器设置
• tracker_settings_global_update(attributes) - 使用JSON属性更新全局跟踪器设置
• tracker_settings_app_get(app_id) - 获取特定于应用的跟踪器设置
• tracker_settings_app_update(app_id, attributes) - 使用JSON属性更新应用跟踪器设置
• tracker_settings_app_delete(app_id, setting) - 删除特定跟踪器设置

开发

该项目需要 uv 进行Python包管理。uv是一个用Rust编写的快速Python包安装程序和解析器。

安装

本地安装

1. 安装开发依赖项：

uv sync --dev

运行服务器

# 开发服务器
uv run python -m piwik_pro_mcp.server  # 启动MCP服务器

# 代码格式化和检查
uv run ruff check .        # 检查代码问题
uv run ruff format .       # 格式化代码

# 测试
uv run pytest tests/      # 运行测试套件
uv run pytest tests/ -v   # 以详细输出运行
uv run pytest tests/ --cov # 运行覆盖率报告

测试

运行测试

# 运行所有测试
uv run pytest 

架构

MCP模块组织

该项目遵循模块化架构，分离关注点并使贡献变得容易：

核心组件

• src/piwik_pro_mcp/server.py：干净的FastMCP服务器创建、配置和主入口点，具有参数解析
• src/piwik_pro_mcp/responses.py：MCP特定的Pydantic响应模型，用于类型化的工具输出
• src/piwik_pro_mcp/api/：集成的API客户端库，具有OAuth2身份验证
• src/piwik_pro_mcp/api/methods/：API端点模块：apps/、analytics/、cdp/、container_settings/、tag_manager/、tracker_settings/
• pyproject.toml：现代Python项目配置，具有uv依赖管理

模块化工具组织

• src/piwik_pro_mcp/tools/：按功能领域组织，便于贡献
  • analytics/：分析操作
    • annotations.py：用户/系统注释工具
  • apps/tools.py：应用管理操作（创建、读取、更新、删除）
  • cdp/：客户数据平台操作
    • audiences.py：受众群体管理操作
    • attributes.py：属性发现操作
    • tools.py：CDP工具注册
  • container_settings/tools.py：容器设置操作
  • tag_manager/：标签管理操作，按资源类型划分
    • tags.py：标签管理操作
    • triggers.py：触发器管理操作
    • variables.py：变量管理操作
    • versions.py：版本管理操作
    • templates.py：模板发现和检索
  • tracker_settings/tools.py：跟踪器设置操作

共享实用工具

• src/piwik_pro_mcp/common/：所有工具模块共享的功能
  • utils.py：客户端创建和验证实用工具
  • templates.py：模板加载实用工具
  • tool_schemas.py：通用工具模式定义
• src/piwik_pro_mcp/tools/parameters.py：参数发现和验证