MCP Matomo

MCP Matomo

A Model Context Protocol (MCP) server that exposes your Matomo Analytics API to Claude and other MCP-compatible AI assistants.

______________________________________________________________________

赞助商

France-Nuage

Host Matomo on sovereign French cloud. EU-only, re-internalisable.

Hook0

Forward Matomo events as signed webhooks to your stack. Self-hostable.

Natalia

AI voice agent calls back the visitors your funnel just lost. 24/7.

Netir

Hire vetted French freelance analytics engineers via marketplace.

NoBullshitConseil

Tech advisory without the bullshit. Data & analytics strategy.

Qualneo

Qualiopi LMS for French trainers. 32 indicators tracked end-to-end.

Recapro

Private AI for client analytics reviews. Transcribe & report sovereign.

有兴趣赞助吗？ 联系

概述

该项目提供了一个MCP服务器，将所有可用的Matomo API方法公开为工具。

快速开始

先决条件

• 防锈稳定(安装)
• 具有API访问权限的Matomo实例
• 您的matomo API令牌（部分）token_auth)

1.建设项目

git clone https://github.com/FGRibreau/mcp-matomo.git
cd mcp-matomo
cargo build --release

2.运行MCP服务器

服务器可以在启动时直接自检您的Matomo实例：

./target/release/mcp-matomo \
  --url https://your-matomo-instance.com \
  --token YOUR_API_TOKEN

服务器将：

1. 连接到您的Matomo实例
2. 获取所有可用的API方法
3. 动态生成工具定义
4. 开始在stdin/stdout上监听MCP消息

How to get your Matomo API token

1. 登录您的Matomo实例
2. 首选 设置 （齿轮图标）→ 个人 → 安全
3. 向下滚动至 身份验证令牌
4. 点击 创建新令牌
5. 为其命名并复制生成的令牌

替代方案：使用预先生成的OpenAPI规范

如果你喜欢更快的启动时间（跳过自检步骤），你可以使用预先生成的OpenAPI规范：

# Use a pre-generated spec
./target/release/mcp-matomo \
  --openapi matomo-api.json \
  --token YOUR_API_TOKEN

注： 您可以通过运行服务器来生成OpenAPI规范 --url 并保存输出或通过使用外部OpenAPI生成器。

配置

克劳德代码

将以下内容添加到您的Claude Code MCP设置中。您可以通过CLI执行此操作：

# Dynamic introspection (recommended)
claude mcp add matomo \
  --command /path/to/mcp-matomo \
  --args "--url" "https://your-matomo-instance.com" \
  --env "MCP_MATOMO_TOKEN=YOUR_API_TOKEN"

或者使用预先生成的OpenAPI规范来加快启动速度：

claude mcp add matomo \
  --command /path/to/mcp-matomo \
  --args "--openapi" "/path/to/matomo-api.json" \
  --env "MCP_MATOMO_TOKEN=YOUR_API_TOKEN"

或者手动将其添加到MCP设置文件中：

{
  "mcpServers": {
    "matomo": {
      "command": "/path/to/mcp-matomo",
      "args": ["--url", "https://your-matomo-instance.com"],
      "env": {
        "MCP_MATOMO_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "matomo": {
      "command": "/absolute/path/to/mcp-matomo",
      "args": ["--url", "https://your-matomo-instance.com"],
      "env": {
        "MCP_MATOMO_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

用法示例

配置后，您可以向Claude提出以下问题：

• *“我昨天接待了多少客人？”*
• *“显示本月访问量排名前10的国家”*
• *“本周我最受欢迎的页面是什么？”*
• *“将上周的流量与前一周进行比较”*
• *“我的访客正在使用哪些设备？”*

Claude将自动使用适当的Matomo API工具来获取和分析您的分析数据。

可用工具

MCP服务器根据您的Matomo实例的API动态生成工具。以下是作为MCP工具公开的受支持的Matomo API方法的完整列表：

参观和交通概况

页面和内容分析

网站搜索

流量来源和推荐人

游客位置和人口统计

设备与技术

访客参与度

基于时间的分析

目标与转化

事件跟踪

用户与人工智能

注： 可用的确切工具取决于您的Matomo实例配置和安装的插件。使用 --url 动态发现特定实例的所有可用方法。

CLI 参考

MCP服务器可以动态地内省Matomo，也可以使用预先生成的OpenAPI规范：

mcp-matomo [OPTIONS]

Options:
  -u, --url             Matomo instance URL (e.g., https://matomo.example.com)
                             When provided, introspects the Matomo API at startup
                             [env: MCP_MATOMO_URL]

  -o, --openapi     Path to a pre-generated OpenAPI JSON file
                             Use for faster startup with a cached spec
                             [env: MCP_MATOMO_OPENAPI_FILE]

  -t, --token         Matomo API token (token_auth)
                             [env: MCP_MATOMO_TOKEN]

  -s, --site-id     Site ID for API introspection [default: 1]
                             [env: MCP_MATOMO_SITE_ID]

  -h, --help                 Print help
  -V, --version              Print version

注： 要么 --url 或 --openapi 必须提供。

______________________________________________________________________

HTTP配置

用户代理

所有HTTP请求都包含一个自定义的User-Agent标头：

User-Agent: mcp-matomo/

这对于在Matomo服务器日志中识别MCP请求或配置防火墙/代理规则非常有用。

额外标头

您可以使用 MCP_MATOMO_EXTRA_HEADERS 环境变量。

示例用例：

• 绕过身份验证代理（零信任、OAuth2代理）
• 添加自定义跟踪标题
• 在多租户设置中传递租户标识符

# Single header
export MCP_MATOMO_EXTRA_HEADERS="X-Auth-Bypass:secret-token"

# Multiple headers
export MCP_MATOMO_EXTRA_HEADERS="Authorization:Bearer xyz,X-Tenant-Id:acme-corp"

# In Claude Code configuration
claude mcp add matomo \
  --command /path/to/mcp-matomo \
  --args "--url" "https://your-matomo-instance.com" \
  --env "MCP_MATOMO_TOKEN=YOUR_API_TOKEN" \
  --env "MCP_MATOMO_EXTRA_HEADERS=X-Custom:value"

JSON配置：

{
  "mcpServers": {
    "matomo": {
      "command": "/path/to/mcp-matomo",
      "args": ["--url", "https://your-matomo-instance.com"],
      "env": {
        "MCP_MATOMO_TOKEN": "YOUR_API_TOKEN",
        "MCP_MATOMO_EXTRA_HEADERS": "X-Auth-Bypass:secret,X-Tenant:acme"
      }
    }
  }
}

发展

# Build debug version
cargo build

# Run tests
cargo test

# Run with logging
RUST_LOG=debug ./target/debug/mcp-matomo --openapi matomo-api.json --token YOUR_TOKEN

故障排除

“没有可用的工具”

如果使用动态内省(--url):

1. 验证您的Matomo实例是否可访问
2. 请检查您的API令牌是否具有正确的权限
3. 尝试指定其他 --site-id 如果你有多个网站

如果使用预先生成的规范(--openapi):

1. 确保您的OpenAPI JSON文件有效并包含路径
2. 尝试使用 --url 而是动态地重新生成规范

“401未经授权”错误

1. 验证您的API令牌是否正确
2. 检查令牌是否具有足够的权限（至少是“查看”权限）
3. 确保令牌正确传递（通过 --token 旗帜或 MCP_MATOMO_TOKEN 任何人）

“连接被拒绝”或超时

1. 验证您的Matomo实例是否可以从您的计算机访问
2. 检查防火墙或VPN要求
3. 如果使用 --url，确保URL正确并包含协议（https://）
4. 如果使用 --openapi，确保规范中的URL与您当前的Matomo URL匹配

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 内置于 rmcp -Rust MCP SDK
• 灵感来自 模型上下文协议 规格