matomo-mcp

Habla con tus análisis de Matomo. Desde Claude, Cursor, VS Code o cualquier cliente MCP.

15 herramientas de análisis seleccionadas y de solo lectura + una vía de escape a la API completa. Un único binario, arranque instantáneo, respetuoso con el contexto.

Inicio rápido · Clientes · Herramientas · Configuración · Preguntas frecuentes

You  ▸ How was traffic yesterday, and where did it come from?

Claude ▸ Yesterday you had 14,472 visits (11,416 unique visitors, 66% bounce rate).
         Top acquisition channels:
         1. Organic search — 6,120 visits (Google 92%)
         2. Direct — 4,890 visits
         3. AI assistants — 1,204 visits (↑ 31% vs. last week)
         Want me to break down which landing pages converted best?

Cada pregunta que tu panel de Matomo puede responder, tu asistente de IA también puede responderla ahora, incluidas las preguntas de seguimiento, las comparaciones y los «por qué».

✨ ¿Por qué matomo-mcp?

Related MCP server: mcp-server-wazuh

🚀 Inicio rápido

1. Instalación

Binario precompilado (Linux, macOS, Windows): descárgalo desde Releases, o:

# Cargo
cargo install matomo-mcp

# From source
cargo install --git https://github.com/Liohtml/matomo-mcp

# Docker
docker pull ghcr.io/liohtml/matomo-mcp

2. Obtén un token de API de Matomo

Matomo → Ajustes (⚙) → Personal → Seguridad → Tokens de autenticación → Crear nuevo token. Solo necesita permisos de solo lectura.

3. Verifica la conexión

matomo-mcp --url https://your-matomo.example.com --token YOUR_TOKEN --check

✓ Connected — Matomo version 5.2.1
✓ Token grants access to 3 site(s):
    #1 My Shop (https://shop.example.com)
    #2 Blog (https://blog.example.com)
    #3 Docs (https://docs.example.com)

4. Conecta tu cliente ⬇

🔌 Conecta tu cliente

claude mcp add matomo \
  --env MATOMO_URL=https://your-matomo.example.com \
  --env MATOMO_TOKEN=YOUR_TOKEN \
  --env MATOMO_DEFAULT_SITE_ID=1 \
  -- matomo-mcp

Añádelo a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "matomo": {
      "command": "matomo-mcp",
      "env": {
        "MATOMO_URL": "https://your-matomo.example.com",
        "MATOMO_TOKEN": "YOUR_TOKEN",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  }
}

.cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "matomo": {
      "command": "matomo-mcp",
      "env": {
        "MATOMO_URL": "https://your-matomo.example.com",
        "MATOMO_TOKEN": "YOUR_TOKEN",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "matomo": {
      "type": "stdio",
      "command": "matomo-mcp",
      "env": {
        "MATOMO_URL": "https://your-matomo.example.com",
        "MATOMO_TOKEN": "${input:matomo-token}",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  },
  "inputs": [
    {
      "id": "matomo-token",
      "type": "promptString",
      "description": "Matomo API token",
      "password": true
    }
  ]
}

Cualquier cliente que hable MCP sobre stdio funciona con la forma genérica:

{
  "command": "matomo-mcp",
  "args": [],
  "env": {
    "MATOMO_URL": "https://your-matomo.example.com",
    "MATOMO_TOKEN": "YOUR_TOKEN",
    "MATOMO_DEFAULT_SITE_ID": "1"
  }
}

{
  "mcpServers": {
    "matomo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MATOMO_URL", "-e", "MATOMO_TOKEN", "-e", "MATOMO_DEFAULT_SITE_ID",
        "ghcr.io/liohtml/matomo-mcp"
      ],
      "env": {
        "MATOMO_URL": "https://your-matomo.example.com",
        "MATOMO_TOKEN": "YOUR_TOKEN",
        "MATOMO_DEFAULT_SITE_ID": "1"
      }
    }
  }
}

Ejecuta el servidor una vez (en una estación de trabajo, una máquina de la LAN o un contenedor) y apunta cualquier número de clientes MCP hacia él:

matomo-mcp --url https://your-matomo.example.com --token YOUR_TOKEN --http 127.0.0.1:8080

Los clientes se conectan a http://127.0.0.1:8080/mcp con el transporte HTTP streamable, por ejemplo:

claude mcp add --transport http matomo http://127.0.0.1:8080/mcp

[!WARNING] El endpoint HTTP no tiene autenticación integrada. Mantenlo vinculado a 127.0.0.1, o coloca un proxy inverso con autenticación (o un cortafuegos) delante antes de exponerlo más allá de localhost.

[!TIP] Configura MATOMO_DEFAULT_SITE_ID y el modelo nunca tendrá que preguntar a qué sitio te refieres. ¿No tienes un token a mano? Pruébalo contra la demo pública: --url https://demo.matomo.cloud --default-site-id 1 (no se necesita token).

🧭 Herramientas

Todas las herramientas aceptan site_id, period (day/week/month/year/range), date (today, yesterday, 2026-07-01, last30 o rangos start,end), un segment opcional (p. ej. deviceType==mobile;country==DE) y un limit de filas.

Prompts para probar

• "Compara el tráfico de esta semana con el de la semana pasada: ¿qué cambió y por qué?"

• "Las 10 mejores páginas de aterrizaje por conversiones este mes, con tasas de rebote."

• "¿Estamos recibiendo tráfico de ChatGPT o Perplexity? Tendencia en 3 meses."

• "¿Qué búsquedas internas no devuelven resultados? Sugiere contenido que deberíamos crear."

• "¿Algo inusual en el registro de visitantes ahora mismo?"

⚙️ Configuración

🆚 ¿En qué se diferencia de FGRibreau/mcp-matomo?

mcp-matomo (que inspiró este proyecto, ¡gracias! 🙏) inspecciona tu instancia de Matomo al arrancar y genera una herramienta MCP por método de API. matomo-mcp adopta el enfoque opuesto:

Si quieres cada método de API como herramienta propia, usa mcp-matomo. Si quieres que el modelo elija de forma fiable la herramienta correcta y nunca sature su contexto, usa matomo-mcp.

🩺 Solución de problemas

O bien pasa --default-site-id 1 (recomendado) o deja que el modelo llame a matomo_list_sites primero.

Ejecuta matomo-mcp --url ... --token ... --check. Si falla: regenera el token (Ajustes → Personal → Seguridad), asegúrate de que tenga al menos acceso de vista al sitio.

MATOMO_URL debe apuntar a la raíz de Matomo — la carpeta que contiene index.php. Para https://example.com/matomo/index.php, usa https://example.com/matomo/.

Inyecta las cabeceras de omisión: --header "CF-Access-Client-Id:..." --header "CF-Access-Client-Secret:..." (o mediante MATOMO_EXTRA_HEADERS).

Eso es el guardián de contexto haciendo su trabajo. Pide menos filas, un rango de fechas más corto, o aumenta --max-response-chars.

🗺️ Roadmap

• Transporte HTTP transmisible (--http, alójalo una vez, conecta muchos clientes)

• matomo_annotations — lee y correlaciona marcadores de despliegue con el tráfico

• Soporte multi-instancia (un servidor, varias instalaciones de Matomo)

• Homebrew tap y manifest de winget

• Listado en el registro MCP (registro oficial mediante server.json, Glama)

¿Quieres alguna de estas antes? Abre un issue — o un PR, consulta CONTRIBUTING.md.

🛠️ Desarrollo

cargo test                                   # 37 tests, fully offline (wiremock)
cargo clippy --all-targets -- -D warnings
cargo run -- --url https://demo.matomo.cloud --default-site-id 1 --check

Decisiones de arquitectura y diseño: docs/ARCHITECTURE.md.

📄 Licencia y créditos

MIT. No afiliado ni respaldado por Matomo — Matomo es una marca registrada de InnoCraft Ltd.

Construido con rmcp, el SDK oficial de MCP para Rust. Inspirado por FGRibreau/mcp-matomo.

• Nombre en el registro MCP: mcp-name: io.github.Liohtml/matomo-mcp

Si matomo-mcp te ahorra una visita al panel, una ⭐ ayuda a otros a encontrarlo.