Matomo MCP Plugin

A complete Model Context Protocol (MCP) server implementation for Matomo that works out of the box with any AI model. No configuration files or NPM requirements needed on the client side - just copy and paste a URL with your API token.

Features

• Complete MCP Server: Full implementation of MCP protocol with tools, prompts, and resources

• Zero Configuration: Works immediately after plugin installation

• HTTP-Based: No WebSocket or stdio transport required

• Secure Authentication: Uses Matomo's built-in API token system

• Extensible Architecture: Easy to add new tools and prompts

• Production Ready: Built following Matomo plugin best practices

Quick Start

1. Install the Plugin

1. Copy this plugin directory to your Matomo plugins/ folder

2. Activate the plugin in Matomo Admin � Plugins

2. Get Your API Token

1. Go to Matomo Admin � Personal � Security

2. Create or copy your API authentication token

3. Connect to AI Models

Claude Desktop Configuration

Add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "matomo": {
      "command": "node",
      "args": ["/path/to/matomo/plugins/MCP/mcp-http-client.js", "https://your-matomo-domain.com/", "YOUR_API_TOKEN"]
    }
  }
}

Direct HTTP API Access

You can also integrate directly via HTTP POST requests to:

https://your-matomo-domain.com/index.php?module=MCP&action=index

Available Tools

Analytics Data Tool (get_analytics_data)

Get comprehensive analytics data from Matomo.

Parameters:

• idSite (integer): Site ID to get data for

• period (string): Time period (day, week, month, year)

• date (string): Date or date range (e.g., "2024-01-01" or "last7")

• metric (string): Metric to retrieve (visits, pageviews, visitors, bounces, conversions)

Example:

{
  "method": "tools/call",
  "params": {
    "name": "get_analytics_data",
    "arguments": {
      "idSite": 1,
      "period": "week",
      "date": "last4",
      "metric": "visits"
    }
  }
}

Site Management Tool (manage_sites)

Manage Matomo sites - list, create, update, or delete.

Parameters:

• action (string): Action to perform (list, create, update, delete, get)

• idSite (integer): Site ID (for get, update, delete)

• siteName (string): Site name (for create, update)

• urls (array): Site URLs (for create, update)

• timezone (string): Timezone

• currency (string): Currency code

Available Prompts

Analytics Reporting (generate_analytics_report)

Generate comprehensive analytics reports and insights.

Arguments:

• report_type: Type of report (summary, performance, growth, technical)

• site_data: Analytics data for analysis

Available Resources

Sites Information (matomo://sites)

List of all sites in your Matomo instance with basic information.

Server Configuration (matomo://config)

Matomo server configuration and system information.

Authentication

The MCP server supports both OAuth 2.0 (recommended) and API Token authentication:

OAuth 2.0 (Recommended)

For production use and MCP client compatibility:

1. Register OAuth Client:

curl -X POST "https://your-matomo.com/index.php?module=MCP&action=register" \
  -d '{"name": "My App", "redirect_uri": "http://localhost:8080/callback", "scopes": ["read"]}'

2. Authorization Flow:

• Direct users to authorization URL

• Exchange authorization code for access token

• Use access token in API calls

3. Use Access Token:

{
  "method": "tools/list"
}

With header: Authorization: Bearer YOUR_ACCESS_TOKEN

See OAuth Guide for complete implementation details.

API Token (Backward Compatibility)

For simple setups, use Matomo API tokens:

1. In request body:

{
  "method": "tools/list",
  "auth": {
    "token": "YOUR_API_TOKEN"
  }
}

2. In Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Permissions & Scopes

Development

Adding New Tools

1. Create a new PHP class in /tools/ directory

2. Implement getToolDefinition() and execute($params) methods

3. The tool will be automatically registered

Example tool structure:

<?php
namespace Piwik\Plugins\MCP\Tools;

class MyTool {
    public function getToolDefinition() {
        return [
            'name' => 'my_tool',
            'description' => 'Description of what the tool does',
            'inputSchema' => [
                'type' => 'object',
                'properties' => [
                    'param1' => [
                        'type' => 'string',
                        'description' => 'Parameter description'
                    ]
                ],
                'required' => ['param1']
            ]
        ];
    }

    public function execute($params) {
        // Tool implementation
        return ['result' => 'success'];
    }
}

Adding New Prompts

1. Create a new PHP class in /prompts/ directory

2. Implement getPromptDefinition() and execute($args) methods

3. The prompt will be automatically registered

API Endpoints

• GET /index.php?module=MCP&action=capabilities - Get server capabilities

• POST /index.php?module=MCP&action=index - Main MCP endpoint

Requirements

• Matomo 5.0+

• PHP 7.4+

• Valid Matomo API token

License

GPL v3+ - Same as Matomo

Support

• Issues: https://github.com/openmost/matomo-mcp-plugin/issues

• Email: ronan@openmost.io