MCP Matomo

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

Sponsors

Natalia 24/7 AI voice and whatsapp agent for customer services

NoBullshitConseil 360° tech consulting

Hook0 Open-Source Webhooks-as-a-Service

France-Nuage Sovereign cloud hosting in France

Interested in sponsoring? Get in touch

Overview

This project provides an MCP server that exposes all available Matomo API methods as tools.

Quick Start

Prerequisites

• Rust stable (install)
• A Matomo instance with API access
• A Matomo API token (token_auth)

1. Build the project

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

2. Run the MCP server

The server can introspect your Matomo instance directly at startup:

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

The server will:

1. Connect to your Matomo instance
2. Fetch all available API methods
3. Generate the tool definitions dynamically
4. Start listening on stdin/stdout for MCP messages

Alternative: Use a pre-generated OpenAPI specification

If you prefer faster startup times (skipping the introspection step), you can use a pre-generated OpenAPI spec:

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

Note: You can generate an OpenAPI spec by running the server with --url and saving the output, or by using an external OpenAPI generator.

Configuration

Claude Code

Add the following to your Claude Code MCP settings. You can do this via the 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"

Or with a pre-generated OpenAPI spec for faster startup:

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

Or manually add it to your MCP settings file:

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude questions like:

• "How many visitors did I have yesterday?"
• "Show me the top 10 countries by visits this month"
• "What are my most popular pages this week?"
• "Compare last week's traffic to the week before"
• "Which devices are my visitors using?"

Claude will automatically use the appropriate Matomo API tools to fetch and analyze your analytics data.

Available Tools

The MCP server dynamically generates tools based on your Matomo instance's API. Below is the complete list of supported Matomo API methods exposed as MCP tools:

Visits & Traffic Overview

Pages & Content Analytics

Site Search

Traffic Sources & Referrers

Visitor Location & Demographics

Devices & Technology

Visitor Engagement

Time-based Analytics

Goals & Conversions

Events Tracking

Users & AI

Note: The exact tools available depend on your Matomo instance configuration and installed plugins. Use --url to dynamically discover all available methods for your specific instance.

CLI Reference

The MCP server can either introspect Matomo dynamically or use a pre-generated OpenAPI spec:

mcp-matomo [OPTIONS]

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

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

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

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

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

Note: Either --url or --openapi must be provided.

Development

# 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

Troubleshooting

"No tools available"

If using dynamic introspection (--url):

1. Verify your Matomo instance is accessible
2. Check that your API token has the correct permissions
3. Try specifying a different --site-id if you have multiple sites

If using a pre-generated spec (--openapi):

1. Make sure your OpenAPI JSON file is valid and contains paths
2. Try using --url instead to regenerate the spec dynamically

"401 Unauthorized" errors

1. Verify your API token is correct
2. Check that the token has sufficient permissions (at least "view" access)
3. Ensure the token is being passed correctly (via --token flag or MCP_MATOMO_TOKEN env var)

"Connection refused" or timeouts

1. Verify your Matomo instance is accessible from your machine
2. Check for firewalls or VPN requirements
3. If using --url, ensure the URL is correct and includes the protocol (https://)
4. If using --openapi, ensure the URL in the spec matches your current Matomo URL

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with rmcp - Rust MCP SDK
• Inspired by the Model Context Protocol specification