Matomo MCP Server

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:

Direct HTTP API Access

You can also integrate directly via HTTP POST requests to:

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:

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:

2. Authorization Flow:

• Direct users to authorization URL
• Exchange authorization code for access token
• Use access token in API calls

3. Use Access Token:

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:

2. In Authorization header:

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:

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