Matomo MCP Client

Matomo MCP服务器

作为Matomo Analytics API客户端的MCP（模型上下文协议）服务器。它将Matomo分析数据作为MCP工具公开，允许任何兼容MCP的LLM客户端（Claude Desktop、Claude Code等）使用自然语言查询您的Matomo实例。

换句话说：这是一个 MCP服务器 （基于stdio的工具）和a Matomo API客户端 （HTTP请求）在一个。

• 直接连接到您的Matomo实例，无需远程代理
• 23种分析工具：流量、页面、搜索、性能、流量源、批量批处理、行演变、细分市场发现和Live-API-based计数
• 在每个基于时间的工具上进行分段过滤，包括 device 移动/桌面切片快捷方式
• matomo_count_visits_by_segment 绕过分段存档陷阱（即使在API令牌不足时也有效 process_new_segment)
• matomo_batch 在一次HTTP往返中运行多个报告
• 通过自定义日期范围 period=range + date=YYYY-MM-DD,YYYY-MM-DD
• 服务器端响应整形： hideColumns, showColumns, filter_truncate, filter_offset, format_metrics
• Docker就绪或使用Node.js运行
• 凭据保留在本地，从不发送给第三方
• 具有指数回退和超时处理的重试逻辑
• 支持自签名证书（内部服务器常用）

安装

选项1:Docker

git clone https://github.com/lucaspretti/matomo-mcp-client
cd matomo-mcp-client
docker build -t matomo-mcp-server .
cp .env.example .env
# Edit .env with your Matomo URL and API token

选项2:Node.js

git clone https://github.com/lucaspretti/matomo-mcp-client
cd matomo-mcp-client
npm install

配置

环境变量

复制 .env.example 到 .env 并填写您的值：

MCP客户端配置

添加到您的MCP客户端配置中（例如。， claude_desktop_config.json):

码头工人

{
  "mcpServers": {
    "matomo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/.env",
        "matomo-mcp-server"
      ]
    }
  }
}

Node.js

{
  "mcpServers": {
    "matomo": {
      "command": "node",
      "args": ["/absolute/path/to/matomo-mcp-client.js"],
      "env": {
        "MATOMO_HOST": "https://matomo.example.com",
        "MATOMO_TOKEN_AUTH": "your_token",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  }
}

保存配置后重新启动MCP客户端。

可用工具

交通

页面

网站搜索

演出

流量来源

分段感知和批处理（v1.7.5–1.7.8）

公共参数

每个基于时间的工具都接受相同的作用域参数：

device 捷径

mobile 捆绑智能手机+平板电脑+平板手机，因为大多数来电者的意思是 “不是桌面”。使用 smartphone 如果你只需要手持设备。

段语法

Matomo细分市场使用 , 对于OR和 ; 对于AND。一些有用的：

• deviceType==smartphone,deviceType==tablet --手机或平板电脑
• countryCode==de;browserCode==FF --使用Firefox的德国游客
• pageUrl=@bulletin/download --看到任何包含以下内容的URL的访问 bulletin/download
• visitorType==returning --仅限回头客

完整参考：https://developer.matomo.org/api-reference/reporting-api-segmentation

分段归档（重要）

Matomo仅返回已 归档 由服务器。如果您的API令牌缺少 process_new_segment 许可 并且该段不是预先存档的，每个报告端点都是如此 (VisitsSummary.get, Actions.getPageUrls等）默默地返回 零 对于每一个指标。这看起来与“无流量匹配”相同，但 实际上“服务器拒绝即时计算”。

如果你通过 segment / device 在未分段时得到空结果 查询返回数据，您正在执行此操作。你有三个选择，按顺序 努力

1. 使用 Live.getLastVisitsDetails 相反 -现场API供应生肉

每次访问数据和 不需要存档，所以任意段 立即工作。缺点：你得到的是一份访问列表，而不是 预先聚合的数字，因此您需要在客户端进行计数。专注的 matomo_count_visits_by_segment 该工具计划用于v1.7.5 （参见 ROADMAP.md).在此之前，请直接致电Matomo：

   curl -s -X POST "$MATOMO_HOST/index.php" \
     --data-urlencode "module=API" \
     --data-urlencode "method=Live.getLastVisitsDetails" \
     --data-urlencode "idSite=35" \
     --data-urlencode "period=month" --data-urlencode "date=2026-03-01" \
     --data-urlencode "segment=pageUrl=@bulletin/download;deviceType==smartphone,deviceType==tablet,deviceType==phablet" \
     --data-urlencode "filter_limit=-1" \
     --data-urlencode "format=JSON" \
     --data-urlencode "token_auth=$MATOMO_TOKEN_AUTH" \
     | jq 'length'

1. 询问您的Matomo管理员 （a）授予 process_new_segment 在你的

令牌，（b）启用 enable_browser_archiving_triggering 对于该网站，或 （c） 预存档常见段（设备、国家等）。这是 如果你严重依赖分段报告，这是正确的解决方案。

1. 通过Matomo UI进行回退：自己构建URL并在

登录到Matomo的浏览器会话——UI使用登录的 用户的权限，而不是API令牌。例子：

   https:///index.php?module=CoreHome&action=index
     &idSite=35&period=range&date=2025-04-24,2026-04-24
     &segment=deviceType%3D%3Dsmartphone%2CdeviceType%3D%3Dtablet%2CdeviceType%3D%3Dphablet

然后导航到行为→ 页面和按URL模式过滤。

MCP服务器本身不受限制，它忠实地将段转发到 Matomo。该限制完全是服务器端的，只影响 聚合报告端点，而不是Live API。

查询示例

• “显示今天的访问统计数据”
• “本周的前10页是什么？”
• “现在有多少访客在线？”
• “人们在网站上搜索什么？”
• “显示上个月的页面加载性能”
• “哪些AI助手正在发送流量？”
• “昨天的首页是什么？”
• “有多少手机访问 /bulletin/download 在过去的12个月里？"
• “过去30天仅限德国游客的首页”
• “本季度智能手机流量份额”

建筑

MCP Client (Claude Desktop/Code)  matomo-mcp-client (stdio)  Matomo API (HTTP POST)

1. MCP客户端通过stdio发送工具调用
2. 服务器转换为Matomo API请求（主体中带有令牌的POST）
3. 结果以JSON格式返回给MCP客户端

学分

最初灵感来自 Openmost的matomo mcp客户端。此版本被重写为直接连接到Matomo API，而无需远程代理，并具有一套扩展的分析工具。

资源

• 模型上下文协议
• Matomo分析
• API参考